검색 / 필터 바

미리보기

로컬 미리보기입니다. 실제 계정, 환경, 실행 데이터에는 영향을 주지 않습니다.

사용법

검색, 카테고리, 상태 필터를 공통 기준선에 정렬하세요. 적용된 조건을 결과 수와 연결하세요. 제어된 상태에서 작고 즉시 적용되는 목록을 파생하세요. 지우면 포커스가 검색 입력으로 돌아갑니다. 카탈로그의 컴포넌트·패턴 인덱스가 이 패턴을 사용합니다.

• 프리미티브가 서버 요청, URL 라우팅, 권한을 처리하리라 기대하지 마세요. 직접 연결하세요.
• 키 입력마다 서버 검색을 보내지 마세요. IME 조합이 끝난 뒤 지연 후 쿼리를 적용하거나 명시적 제출을 요구하세요.
• 이전 응답이 이후 응답을 덮어쓰지 않게 하세요. 이전 요청을 취소하거나 응답 순서를 확인하세요.
• 서버 로딩을 빈 결과로 보여주지 마세요. 로딩 결과에 aria-busy를 표시하세요.
• 요청이 실패해도 입력을 지우지 마세요. 유지하고 재시도를 제공하세요.
• 권한 제한을 숨기지 마세요. 설명하세요.

구성

FilterBar.Root(named search form) → Controls → Field(label + Input/Select) + Actions; optional applied-filter buttons and Summary(status). Results remain outside the form.

키보드와 접근성

• 입력은 표준 편집 키를 사용합니다. Base UI가 Select의 화살표 키, Enter, Escape를 처리합니다.
• Root는 submit이나 reset을 가로채지 않으므로 호출하는 쪽에서 onSubmit과 onReset을 연결하세요. 즉시 적용 모드에서는 preventDefault를 호출해 Enter가 페이지를 다시 로드하지 않게 하세요.
• 적용된 필터를 제거하면 포커스가 남은 입력으로 이동합니다.
• 결과 알림은 텍스트 요약만 갱신합니다. 전체 목록은 라이브 영역이 아닙니다.

각 컨트롤에 목적을 설명하는 이름을 지정하세요. 오류 메시지를 해당 컨트롤에 연결하고, 상태를 색만으로 알리지 마세요. 자동 검사는 수동 키보드 및 보조 기술 테스트를 대신하지 않습니다.

예시 코드

공유 컴포넌트는 디자인 토큰에서 스타일을 가져옵니다. 각 예시는 자체 구성과 접근성 속성을 설정합니다. 호출하는 화면이 콜백, ref, 제품 데이터를 정의합니다.

import { FilterBar, Input, Select, Button } from '@surflane/ui'

<FilterBar.Root
  label='Filter resources'
  onSubmit={(e) => e.preventDefault()}
  onReset={(e) => {
    e.preventDefault()
    resetFilters()
  }}
>
  <FilterBar.Controls>
    <FilterBar.Field width='search'>
      Search
      <Input
        type='search'
        value={query}
        onChange={(e) => setQuery(e.target.value)}
      />
    </FilterBar.Field>
    <FilterBar.Field>
      State
      <Select
        aria-label='Resource state'
        value={state}
        onValueChange={setState}
        options={states}
      />
    </FilterBar.Field>
    <FilterBar.Actions>
      <Button type='reset'>Clear filters</Button>
    </FilterBar.Actions>
  </FilterBar.Controls>
  <FilterBar.Summary>{count} results</FilterBar.Summary>
</FilterBar.Root>

주요 API

표는 공통 래퍼의 주요 props를 나열합니다. 전체 타입은 패키지 타입 선언을 참조하세요.

관련 토큰