react-dropdown - GitLite

KO | EN

gitlite — search

#hacktoberfest #react #ai #typescript #android #rust #docker #java #awesome #kubernetes #vue #security #mcp #openai

react-dropdown

(★ 673)

🔽 A dead simple dropdown component for React

파일 탐색기

최종 버전 다운로드 (.zip)

- - ci.yml
  - pages.yml
  - release.yml
- index.cjs
- index.cjs.map
- index.d.ts
- index.d.ts.map
- index.js
- index.js.map
- - main.tsx
  - style.css
- index.html
- css.d.ts
- index.tsx
- Dropdown.test.tsx
- setup.ts
.gitignore
CHANGELOG.md
LICENSE
package-lock.json
package.json
README.md
style.css
tsconfig.build.json
tsconfig.json
vite.demo.config.ts
vite.lib.config.ts
vitest.config.ts

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/fraserxu/react-dropdown

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd react-dropdown

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Node.js

쉬움 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Node.js npm 명령어를 쓰려면 Node.js가 설치되어 있어야 합니다. LTS(장기지원) 버전을 추천합니다.

npm install react-dropdown

package.json에 명시된 라이브러리들을 내려받아 설치합니다.

npm install

package.json에 명시된 라이브러리들을 내려받아 설치합니다.

npm run dev # local example

개발/실행 서버를 켭니다.

npm test # interaction tests

이 명령어를 터미널에 그대로 입력해 실행하세요.

npm run typecheck

이 명령어를 터미널에 그대로 입력해 실행하세요.

✅ 명령어 실행 후 터미널에 나타나는 주소(보통 http://localhost:3000 형태)를 브라우저에서 열어보세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# react-dropdown

[![npm](https://img.shields.io/npm/v/react-dropdown.svg)](https://www.npmjs.com/package/react-dropdown)
[![CI](https://github.com/fraserxu/react-dropdown/actions/workflows/ci.yml/badge.svg)](https://github.com/fraserxu/react-dropdown/actions/workflows/ci.yml)
[![license](https://img.shields.io/npm/l/react-dropdown.svg)](https://raw.githubusercontent.com/fraserxu/react-dropdown/master/LICENSE)

A lightweight, accessible dropdown component for React 18 and 19.

`react-dropdown` is for the common case where a native `<select>` is too difficult to style, but a large select framework would be excessive. It supports single selection, option groups, controlled and uncontrolled state, custom rendering, keyboard navigation, and TypeScript without runtime dependencies.

## Install

```sh
npm install react-dropdown
```

Import the component and its default styles:

```tsx
import Dropdown, { type Option } from 'react-dropdown'
import 'react-dropdown/style.css'

const options = [
  { value: 'one', label: 'One' },
  { value: 'two', label: 'Two' },
  {
    type: 'group' as const,
    name: 'More',
    items: [
      { value: 'three', label: 'Three' },
      { value: 'four', label: 'Four', disabled: true },
    ],
  },
]

function Example() {
  const handleChange = (option: Option) => {
    console.log(option.value)
  }

return (
    <Dropdown
      aria-label="Number"
      options={options}
      onChange={handleChange}
      placeholder="Select an option"
    />
  )
}
```

Primitive options are supported too:

```tsx
<Dropdown options={['one', 'two', 'three']} defaultValue="one" />
```

String, number, and boolean values are supported. Labels may be any `ReactNode`.

## Controlled state

Control the selected value, the open state, or both:

```tsx
const [value, setValue] = useState<Option | null>(null)
const [open, setOpen] = useState(false)

<Dropdown
  options={options}
  value={value}
  onChange={setValue}
  open={open}
  onOpenChange={setOpen}
/>
```

Use `null` to clear a controlled value. Use `defaultValue` or `defaultOpen` for uncontrolled initial state.

## Accessible labels

Give every dropdown an accessible name with a visible label:

```tsx
<label id="country-label">Country</label>
<Dropdown aria-labelledby="country-label" options={countries} />
```

Or use `aria-label` when there is no visible label:

```tsx
<Dropdown aria-label="Country" options={countries} />
```

The trigger implements a select-only combobox with a listbox popup. It supports:

- `Enter` or `Space` to open and select.
- `ArrowDown` and `ArrowUp` to open and move through options.
- `Home` and `End` to move to the first or last enabled option.
- `Escape` to close.
- `Tab` to close and continue normal page navigation.
- Disabled options, named groups, selected state, and active-descendant announcements.

## Forms

Pass `name` to include the selected value in native form submission:

```tsx
<Dropdown name="country" options={countries} defaultValue="au" />
```

The component renders a hidden input using the selected option value. Pass `form` to associate it with a form by ID.

## Custom rendering

```tsx
<Dropdown
  options={options}
  renderOption={(option, { active, selected }) => (
    <span>
      {selected ? '✓ ' : ''}
      {option.label}
      {active ? ' ←' : ''}
    </span>
  )}
  optionClassName={(_option, state) => (state.active ? 'my-active-option' : undefined)}
/>
```

Options may also define `className` and `data`:

```tsx
const options = [
  {
    value: 'one',
    label: 'One',
    className: 'important-option',
    data: { analytics: 'option-one' },
  },
]
```

## API

| Prop | Type | Default | Purpose |
| --- | --- | --- | --- |
| `options` | `DropdownEntry[]` | required | Primitive options, option objects, or groups. |
| `value` | `Option \| string \| number \| boolean \| null` | — | Controlled selected value. |
| `defaultValue` | same as `value` | `null` | Initial uncontrolled value. |
| `open` | `boolean` | — | Controlled popup state. |
| `defaultOpen` | `boolean` | `false` | Initial uncontrolled popup state. |
| `onChange` | `(option: Option) => void` | — | Called after a user selects an option. |
| `onOpenChange` | `(open: boolean) => void` | — | Called when the popup requests an open-state change. |
| `onFocus` | `(open: boolean) => void` | — | Called when the trigger receives focus. |
| `placeholder` | `ReactNode` | `"Select..."` | Content shown without a selection. |
| `disabled` | `boolean` | `false` | Disables the trigger. |
| `name` | `string` | — | Adds a hidden form input. |
| `form` | `string` | — | Associates the hidden input with a form ID. |
| `id` | `string` | generated | Sets the trigger ID and derived popup IDs. |
| `tabIndex` | `number` | browser default | Overrides the trigger's tab order. |
| `aria-label` | `string` | — | Gives the control an accessible name. |
| `aria-labelledby` | `string` | — | References a visible label. |
| `renderOption` | `(option, state) => ReactNode` | option label | Custom option contents. |
| `noOptionsContent` | `ReactNode` | `"No options found"` | Empty-state contents. |
| `arrowClosed` / `arrowOpen` | `ReactNode` | CSS arrow | Custom trigger arrows. Provide both. |

The styling props are `baseClassName`, `className`, `controlClassName`, `placeholderClassName`, `menuClassName`, `optionClassName`, and `arrowClassName`.

The forwarded ref points to the trigger `HTMLButtonElement`.

## Styling

The default stylesheet retains the familiar class names:

- `.Dropdown-root`
- `.Dropdown-control`
- `.Dropdown-placeholder`
- `.Dropdown-arrow-wrapper` and `.Dropdown-arrow`
- `.Dropdown-menu`
- `.Dropdown-group` and `.Dropdown-title`
- `.Dropdown-option`
- `.Dropdown-noresults`

State classes include `.is-open`, `.is-selected`, `.is-active`, and `.is-disabled`.

Set `baseClassName` to replace the `Dropdown` prefix when supplying all of your own styles.

## Migrating from 1.x

Version 2 is a deliberate accessibility and packaging reset:

- React 18 or 19 is required.
- The package now ships ESM and CommonJS with an `exports` map.
- The trigger is a focusable button with `role="combobox"`; CSS that assumes `.Dropdown-control` is a `<div>` may need adjustment.
- `onFocus` now runs when the trigger actually receives focus.
- `onChange` returns the complete normalized option, including `className`, `disabled`, and `data` when present.
- `value={null}` clears a controlled selection. `0` and `false` are valid values.
- The menu uses semantic `<ul>` and `<li>` elements. Prefer class selectors over element selectors in custom CSS.
- `optionClassName`, `renderOption`, `open`, and `onOpenChange` replace common 1.x workarounds.
- The old global `.Dropdown-disabled` class is now applied directly to the disabled control.

## Development

```sh
npm install
npm run dev       # local example
npm test          # interaction tests
npm run typecheck
npm run build
npm run check     # all release checks
```

## License

MIT