본문으로 건너뛰기

Select

Select 컴포넌트는 사용자가 미리 정의된 옵션 목록에서 선택할 수 있는 드롭다운 선택 인터페이스를 제공합니다. 카테고리별로 옵션을 그룹화하고, 개별 옵션의 비활성화를 지원하며, 다양한 스타일 옵션과 함께 접근성이 향상된 경험을 제공합니다. 라이트/다크 테마를 자동으로 지원합니다.

기능​

  • 드롭다운 형태의 선택 인터페이스
  • 단일 항목 선택 지원
  • 카테고리별 옵션 그룹화
  • 개별 옵션 비활성화 기능
  • 시각적 포커스 및 선택 표시
  • 키보드 접근성 지원
  • 라이트/다크 테마 자동 적용
  • 반응형 디자인
  • 제어/비제어 컴포넌트 모두 지원

가져오기​

import { Select } from 'react-components-library';

기본 사용법​

<Select
  placeholder="옵션 선택"
  options={[
    { value: 'option1', label: '옵션 1' },
    { value: 'option2', label: '옵션 2' },
    { value: 'option3', label: '옵션 3' },
    { value: 'option4', label: '옵션 4' },
  ]}
  onChange={(value) => console.log('선택된 값:', value)}
/>

예제​

그룹화된 옵션​

카테고리별로 옵션을 그룹화하여 정리된 형태로 표시할 수 있습니다.

<Select
  placeholder="카테고리에서 선택"
  options={[
    {
      label: '과일',
      options: [
        { value: 'apple', label: '사과' },
        { value: 'banana', label: '바나나' },
        // ... 더 많은 옵션
      ],
    },
    {
      label: '채소',
      options: [
        { value: 'aubergine', label: '가지' },
        { value: 'broccoli', label: '브로콜리' },
        // ... 더 많은 옵션
      ],
    },
    // ... 더 많은 그룹
  ]}
  onChange={(value) => console.log('선택된 값:', value)}
/>

기본 선택 값 설정​

defaultValue 속성을 사용하여 초기 선택 값을 설정할 수 있습니다.

<Select
  placeholder="선택하세요"
  defaultValue="option2"
  options={[
    { value: 'option1', label: '옵션 1' },
    { value: 'option2', label: '옵션 2' },
    { value: 'option3', label: '옵션 3' },
  ]}
  onChange={(value) => console.log('선택된 값:', value)}
/>

비활성화된 옵션​

특정 옵션을 비활성화하여 선택할 수 없게 만들 수 있습니다.

<Select
  placeholder="선택하세요"
  options={[
    { value: 'option1', label: '옵션 1' },
    { value: 'option2', label: '옵션 2', disabled: true },
    { value: 'option3', label: '옵션 3' },
    { value: 'option4', label: '옵션 4', disabled: true },
  ]}
  onChange={(value) => console.log('선택된 값:', value)}
/>

컴포넌트 비활성화​

전체 Select 컴포넌트를 비활성화할 수 있습니다.

<Select
  placeholder="비활성화됨"
  disabled={true}
  options={[
    { value: 'option1', label: '옵션 1' },
    { value: 'option2', label: '옵션 2' },
    { value: 'option3', label: '옵션 3' },
  ]}
/>

제어 컴포넌트로 사용​

상태 관리를 통해 제어 컴포넌트로 사용할 수 있습니다.

선택된 값: 없음
function ControlledDemo() {
  const [value, setValue] = useState('');
  
  return (
    <>
      <Select
        placeholder="제어 컴포넌트"
        value={value}
        options={[
          { value: 'option1', label: '옵션 1' },
          { value: 'option2', label: '옵션 2' },
          { value: 'option3', label: '옵션 3' },
        ]}
        onChange={(newValue) => setValue(newValue)}
      />
      <div>선택된 값: {value || '없음'}</div>
      <Button 
        variant="secondary" 
        size="sm" 
        onClick={() => setValue('')}
      >
        초기화
      </Button>
    </>
  );
}

드롭다운 높이 제한​

maxDropdownHeight 속성을 사용하여 드롭다운 메뉴의 최대 높이를 제한할 수 있습니다.

<Select
  placeholder="스크롤 가능한 드롭다운"
  maxDropdownHeight={200}
  options={Array.from({ length: 20 }, (_, i) => ({
    value: `option-${i + 1}`,
    label: `옵션 ${i + 1}`
  }))}
  onChange={(value) => console.log('선택된 값:', value)}
/>

API​

Select​

속성타입기본값설명
placeholderstring'옵션 선택'기본적으로 표시할 플레이스홀더 텍스트
valuestring-현재 선택된 값 (제어 컴포넌트로 사용 시)
defaultValuestring-기본 선택 값 (비제어 컴포넌트로 사용 시)
options(SelectOption | SelectGroup)[][]선택 가능한 옵션 목록 또는 그룹화된 옵션 목록
disabledbooleanfalse컴포넌트 비활성화 여부
size'sm' | 'md' | 'lg''md'컴포넌트의 크기
theme'light' | 'dark' | 'auto''light'테마 모드
onChange(value: string) => void-선택 시 호출될 콜백 함수
onOpenChange(open: boolean) => void-드롭다운 열림/닫힘 시 호출될 콜백 함수
classNamestring-컴포넌트에 적용할 추가 CSS 클래스
styleReact.CSSProperties-컴포넌트에 적용할 인라인 스타일
requiredbooleanfalse선택 필수 여부
idstring-컴포넌트 ID
namestring-컴포넌트 이름 (폼 제출용)
maxDropdownHeightnumber-최대 드롭다운 높이 (px)

타입​

interface SelectOption {
  /**
   * 옵션 값
   */
  value: string;
  
  /**
   * 옵션 레이블
   */
  label: string;
  
  /**
   * 옵션 비활성화 여부
   */
  disabled?: boolean;
}

interface SelectGroup {
  /**
   * 그룹 레이블
   */
  label: string;
  
  /**
   * 그룹 내 옵션 목록
   */
  options: SelectOption[];
}