v0.10.0

ComponentsP3 본문

SearchField

검색 입력 — SearchIcon leading 고정, 값이 있으면 지우기 버튼 노출, Enter로 onSearch 호출. 비제어(defaultValue) 우선이라 서버 MDX에서도 그대로 동작합니다.

마지막 업데이트 2026-06-11

한눈에#

검색 입력 — SearchIcon leading 고정, 값이 있으면 지우기 버튼 노출, Enter로 onSearch 호출.

  • SearchIcon 고정
  • 지우기 버튼
  • Enter onSearch
  • 비제어 우선

기본 — 입력하면 지우기 버튼이 나타납니다

사용 시점#

검색어 필터/조회면 SearchField — 칩 태그나 명령 팔레트면 목적에 맞는 컴포넌트를 가리킵니다.

쓴다

목록·페이지를 검색어로 필터/조회

대신 Autocomplete
Autocomplete

제안 목록에서 골라 칩으로 쌓는 태그 입력

대신 Command
Command

⌘K 명령 팔레트(명령 리스트 + 키보드 탐색)

플레이그라운드#

컨트롤로 props를 조작하면 미리보기와 코드가 실시간 갱신됩니다.

import { SearchField } from '@wds/ui-web';

<SearchField aria-label="검색" placeholder="검색어를 입력하세요" />

변형#

defaultValue — 초기값이 있으면 지우기 버튼이 바로 노출

지우기 버튼은 값이 있고 disabled가 아닐 때만 렌더됩니다. 클릭하면 값을 비우고 포커스를 입력으로 되돌립니다.

크기#

높이는 input.height(= control.height-md, 44px) 단일 — Input·Button md와 줄맞춤이 자동으로 일치합니다.

상태#

Disabled — 지우기 버튼도 숨김
  • Focus — 래퍼 :focus-within이 input.border-focus 보더 + 18% 링을 그립니다
  • Disabled — input.bg-disabled 배경 + 지우기 버튼 미노출

가이드#

권장

  • 목록·페이지 검색처럼 검색어를 입력해 결과를 거르는 단순 검색에 쓴다
  • Enter로 onSearch를 실행하고, 한글 IME 조합 확정 Enter는 자체적으로 무시한다
  • aria-label이나 외부 label로 검색 입력에 접근 이름을 붙인다

지양

  • SearchField로 명령 팔레트(⌘K, 키보드로 명령 탐색·실행)를 흉내 낸다 — Command를 쓴다
  • 선택 결과를 칩으로 쌓는 태그 입력으로 쓴다 — Autocomplete를 쓴다
  • leading SearchIcon 외에 다른 의미의 아이콘을 넣어 "검색"이라는 신호를 흐린다

Props#

Prop타입기본값설명
onSearch(value: string) => void—Enter 시 현재 값으로 호출 — 한글 IME 조합 확정 Enter는 제외
clearLabelstring'지우기'지우기 버튼 aria-label
placeholderstring'검색어 입력'플레이스홀더 — 한국어 기본값 제공
…restOmit<InputHTMLAttributes, 'type' | 'value'>—defaultValue · onChange · disabled 등은 내부 input으로 전달 — 비제어 전용(value 차단)

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/activecolor.surface-hover / color.surface-pressed · color.text
포커스 링color.primary 18% 링 (지우기 버튼은 color.focus-ring 2px 아웃라인)
간격space.2 · space.3
모션duration.fast + ease.standard