SearchField
검색 입력 — SearchIcon leading 고정, 값이 있으면 지우기 버튼 노출, Enter로 onSearch 호출. 비제어(defaultValue) 우선이라 서버 MDX에서도 그대로 동작합니다.
마지막 업데이트 2026-06-11
한눈에#
검색 입력 — SearchIcon leading 고정, 값이 있으면 지우기 버튼 노출, Enter로 onSearch 호출.
- SearchIcon 고정
- 지우기 버튼
- Enter onSearch
- 비제어 우선
기본 — 입력하면 지우기 버튼이 나타납니다
사용 시점#
검색어 필터/조회면 SearchField — 결과 표면이나 명령 팔레트면 목적에 맞는 컴포넌트를 가리킵니다.
권장 — 이렇게 쓰세요
지양 — 이러지 마세요
쓴다 — 목록·페이지를 검색어로 필터/조회
대신 Autocomplete — 제안 목록에서 골라 칩으로 쌓는 태그 입력
대신 SearchCommand — 검색 결과 목록과 스니펫을 같은 표면에서 보여줄 때
대신 Command — ⌘K / Ctrl K 명령 팔레트(명령 리스트 + 키보드 탐색)
플레이그라운드#
컨트롤로 props를 조작하면 미리보기와 코드가 실시간 갱신됩니다.
SearchField를 직접 조작해 보세요
속성·테마·토큰을 바꾸고 React·Flutter 코드를 확인하는 풀스크린 빌더로 엽니다.
플레이그라운드는 넓은 작업 영역이 필요해 웹·태블릿에서 편집할 수 있어요.
변형#
지우기 버튼은 값이 있고 disabled가 아닐 때만 렌더됩니다. 클릭하면 값을 비우고 포커스를 입력으로 되돌립니다.
크기#
높이는 input.height(= control.height-md, 44px) 단일 — Input·Button md와
줄맞춤이 자동으로 일치합니다.
상태#
- Focus — 래퍼
:focus-within이input.border-focus보더 + 18% 링을 그립니다 - Disabled —
input.bg-disabled배경 + 지우기 버튼 미노출
가이드#
권장
- 목록·페이지 검색처럼 검색어를 입력해 결과를 거르는 단순 검색에 쓴다
- Enter로 onSearch를 실행하고, 한글 IME 조합 확정 Enter는 자체적으로 무시한다
- aria-label이나 외부 label로 검색 입력에 접근 이름을 붙인다
지양
- SearchField로 검색 결과 패널을 흉내 낸다 — SearchCommand를 쓴다
- SearchField로 명령 팔레트(⌘K / Ctrl K, 키보드로 명령 탐색·실행)를 흉내 낸다 — Command를 쓴다
- 선택 결과를 칩으로 쌓는 태그 입력으로 쓴다 — Autocomplete를 쓴다
- leading SearchIcon 외에 다른 의미의 아이콘을 넣어 "검색"이라는 신호를 흐린다
Props#
| Prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
onSearch | (value: string) => void | — | Enter 시 현재 값으로 호출 — 한글 IME 조합 확정 Enter는 제외 |
clearLabel | string | 지우기 | 지우기 버튼 aria-label |
ref | Ref<HTMLInputElement> | — | 내부 <input>으로 병합 전달되는 ref (React 19 ref-as-prop) |
className은 래퍼(div)에 적용됩니다 — 폭 제어 등 레이아웃 조정용.
접근성#
type="search"네이티브 입력 — 라벨은 소비자 책임(aria-label또는 외부<label htmlFor>)- leading SearchIcon은 장식(
aria-hidden) — 지우기 버튼은clearLabel로 접근성 이름을 갖는 실제 버튼 - Enter 검색은
isComposing을 확인해 한글 IME 조합 확정 Enter를 무시합니다 - 지우기 후 포커스를 입력으로 복원해 키보드 흐름이 끊기지 않습니다
- 포커스 링은 래퍼
:focus-within— 아이콘 포함 전체가 하나의 컨트롤로 인지
토큰#
component 토큰 없이 Input의 component 토큰(input.*)과 semantic을 직접
소비합니다(신설 기준 §4 미충족 — Input 변형이라 결정을 공유).
| 속성 | 토큰 |
|---|---|
| 배경/글자 | input.bg · input.fg (disabled input.bg-disabled) |
| 보더 | input.border → focus input.border-focus |
| 높이/라운드 | input.height · input.radius |
| 플레이스홀더 | input.placeholder |
| 아이콘 | icon.size-md(leading) · icon.size-sm(지우기) + color.text-muted |
| 지우기 hover/active | color.surface-hover / color.surface-pressed · color.text |
| 포커스 링 | color.primary 18% 링 (지우기 버튼은 color.focus-ring 2px 아웃라인) |
| 간격 | space.2 · space.3 |
| 모션 | duration.fast + ease.standard |