Autocomplete

입력 중 추천 목록을 보여주는 자동 완성 입력 컴포넌트

Autocomplete#

텍스트 입력 중 필터링된 추천 목록을 드롭다운으로 보여주는 자동 완성 컴포넌트입니다. 입력값으로 suggestions를 대소문자 무시 contains 매칭으로 필터링하고, 추천을 선택하면 mode에 따라 적용합니다.

Live Preview#

Web

Flutter

Loading Flutter...

class AutocompleteDefaultExample extends StatefulComponent {
  const AutocompleteDefaultExample({super.key});

  @override
  State<AutocompleteDefaultExample> createState() =>
      _AutocompleteDefaultExampleState();
}

class _AutocompleteDefaultExampleState
    extends State<AutocompleteDefaultExample> {
  String _value = '';

  @override
  Component build(BuildContext context) {
    return Autocomplete(
      suggestions: const ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry'],
      value: _value,
      placeholder: 'Search fruits...',
      onSelected: (v) => setState(() => _value = v),
    );
  }
}

class AutocompleteDefaultExample extends StatefulWidget {
  const AutocompleteDefaultExample({super.key});

  @override
  State<AutocompleteDefaultExample> createState() =>
      _AutocompleteDefaultExampleState();
}

class _AutocompleteDefaultExampleState
    extends State<AutocompleteDefaultExample> {
  String _value = '';

  @override
  Widget build(BuildContext context) {
    return Autocomplete(
      suggestions: const ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry'],
      value: _value,
      placeholder: 'Search fruits...',
      onSelected: (v) => setState(() => _value = v),
    );
  }
}

사용 시기 (When to Use)#

이 컴포넌트를 사용하세요:

자유 입력이 가능하면서 추천을 보조로 제공할 때
검색 입력에 추천어를 함께 노출할 때

대신 다른 컴포넌트를 사용하세요:

Select: 미리 정의된 옵션 중에서만 선택해야 할 때

추천 선택이 항상 입력값을 통째로 교체하기만 하면 되는 경우는 Autocomplete(mode: CoreAutocompleteMode.replaceAll)을 쓰세요 (옛 Datalist는 이 모드로 통합됐습니다).

기본 사용법 (Basic Usage)#

// 기본 자동 완성
Autocomplete(
  suggestions: ['Apple', 'Banana', 'Cherry'],
  placeholder: 'Search fruits',
  onSelected: (value) => print('Selected: value'),
)

// 추천 적용 모드 지정
Autocomplete(
  suggestions: tags,
  mode: CoreAutocompleteMode.append,
  onSelected: handleSelected,
)

// 기본 자동 완성
Autocomplete(
  suggestions: ['Apple', 'Banana', 'Cherry'],
  placeholder: 'Search fruits',
  onSelected: (value) => print('Selected: value'),
)

// 추천 적용 모드 지정
Autocomplete(
  suggestions: tags,
  mode: CoreAutocompleteMode.append,
  onSelected: handleSelected,
)

Props / Parameters#

속성	타입	기본값	설명
`suggestions`	`List<String>`	필수	추천 문자열 목록
`value`	`String?`	`null`	현재 입력 값
`placeholder`	`String?`	`null`	입력 안내 문구
`enabled`	`bool`	`true`	입력 가능 여부
`required`	`bool`	`false`	필수 입력 여부
`name`	`String?`	`null`	폼 제출용 필드 이름
`mode`	`CoreAutocompleteMode`	`replaceWord`	추천 적용 방식
`onChanged`	`ValueChanged<String>?`	`null`	입력 값 변경 콜백
`onSelected`	`ValueChanged<String>?`	`null`	추천 선택 콜백
`autocompleteStyle`	`CoreAutocompleteStyle?`	`null`	드롭다운 chrome 오버라이드

동작 스펙 (Behavior)#

필터링: 입력값으로 추천 목록을 대소문자 무시 contains 매칭. 입력이 비면 전체 노출
드롭다운 표시: 포커스 시 열림, 외부 클릭 / blur 시 닫힘
추천 적용 모드:
- replaceAll / replaceWord: 입력 전체를 추천으로 교체
- append: 기존 입력 뒤에 추천을 덧붙임

접근성 (Accessibility)#

드롭다운: role="listbox"
각 옵션: role="option" + data-value

크로스 플랫폼 차이점 (Platform Differences)#

항목	Flutter	Web
클래스명	`Autocomplete`	`Autocomplete`
입력 필드	`TextField` (EditableText)	`TextField` (`<input>`)
드롭다운	`Popover` 떠있는 패널	`Popover` 떠있는 패널

추천 드롭다운은 양 플랫폼 모두 통일 Popover의 떠있는 패널로 렌더되어, 조상의 overflow/transform 클리핑을 벗어나고 뷰포트 안에 머물도록 flip/shift 됩니다 (Select와 동일). 패널 box chrome(배경·border·radius·shadow)은 autocompleteStyle.popoverStyle(→ CorePopupStyle) 단일 출처로 흐릅니다.

TextField: 추천 없는 텍스트 입력
Select: 옵션 중 선택