> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.

# Getting Started

Requires React and React DOM 18.2 at minimum and also supports React 19. Both peer dependency ranges are `^18.2.0 || ^19.0.0`. The date pickers' `dayjs` dependency is installed automatically. Install tao-ui with your preferred package manager.


```sh [npm]
npm install @rockshin/tao-ui
```

```sh [yarn]
yarn add @rockshin/tao-ui
```

```sh [pnpm]
pnpm add @rockshin/tao-ui
```

```sh [bun]
bun add @rockshin/tao-ui
```

```sh [deno]
deno add npm:@rockshin/tao-ui
```

## Add the provider

Wrap your application once with `TaoProvider`. Components inherit settings such as size, disabled state, and theme mode.

```tsx
import { Button, TaoProvider } from '@rockshin/tao-ui';

export default function App() {
  return (
    <TaoProvider size="medium">
      <Button>Continue</Button>
    </TaoProvider>
  );
}
```

## Component imports

Component entries load only their component dependencies and shared theme styles. No separate CSS import is needed. The root entry remains available and includes all component styles.

```tsx
import { Button, type ButtonProps } from '@rockshin/tao-ui/button';
import { TaoProvider } from '@rockshin/tao-ui/provider';
```

Entry names use kebab-case, such as `/input-number`, `/range-picker`, and `/form-layout`. Related exports share an entry: `CheckboxGroup` uses `/checkbox`, and `HeadlessInputNumber` uses `/number-input`.

## Control field values

For Input, Textarea, InputNumber, Select, DatePicker, and RangePicker, an explicit `value={undefined}` is a controlled empty value. Omit `value` and use `defaultValue` for an uncontrolled field. Form fields can be cleared with `form.setFieldsValue({ field: undefined })` without remounting the control.

## Use dark mode

Set the theme mode on the provider. Portaled components inherit the same theme.

```tsx
<TaoProvider theme={{ mode: 'dark' }}>
  <App />
</TaoProvider>
```

Continue with the [Button component](https://rickyshin93.github.io/tao-ui/components/button.md).

## Accessibility and ARIA

Use `FormField` or `Form.Item` to associate labels, help and validation messages with controls. Input, Textarea, InputNumber, Select, Checkbox, Radio, Switch, DatePicker and RangePicker forward field ARIA attributes to their interactive elements; CheckboxGroup and RadioGroup expose group labels and validation messages. Placeholders do not replace field labels.

```tsx
<FormField label="Travel dates" required error="Choose valid dates">
  <RangePicker placeholder={['Start date', 'End date']} />
</FormField>
```

Radio maps `aria-required` to native `required`; an explicit `required` prop takes precedence. Group options retain their native disabled state, including explicit `disabled={false}` overrides.

Desktop date inputs expose `combobox` semantics. ArrowDown opens the calendar and moves focus into it; Escape closes it and returns focus to the input. RangePicker combines explicit ARIA labels and each endpoint placeholder to distinguish its inputs. Native labels can instead target `id` and `${id}-end`. Calendar, month, year and time choices expose selection state.

- Name Tabs with `aria-label` or `aria-labelledby`; text panels are reachable with Tab.
- Give Modal, Drawer and Popover a visible `title` or explicit ARIA name. Popconfirm associates its question and description automatically.
- Spinner accepts `aria-label`, defaults to `Loading` without a tip, and marks wrapped content `aria-busy` throughout loading, including its display delay.
- Applications must still supply meaningful names for icon-only buttons.

Automated checks cover DOM semantics and keyboard interaction in React 18/19; test composed screens with a browser and screen reader as well. See the [WAI-ARIA date combobox example](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-datepicker/) and [Tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/).
