# Core concepts

> The ideas shared by every component: controlled vs uncontrolled state, onValueChange vs onValueChanging, sheets and drafts, fields, iOS / Material / web designs, theming and slot styles.

Every component follows the same handful of conventions. Learn them once and you know the whole library.

## Controlled and uncontrolled

Most pickers can be used either way:

```tsx
// Controlled: you own the state
const [date, setDate] = useState(new Date());
<TimePicker value={date} onValueChange={setDate} />

// Uncontrolled: the component owns it; you only listen
<TimePicker defaultValue={new Date()} onValueChange={(d) => console.log(d)} />
```

| Component | Controlled | Uncontrolled |
| --- | --- | --- |
| `WheelPicker` | `value` | `defaultValue` |
| `TimePicker` | `value` | `defaultValue` (default: now) |
| `DatePicker` / `Calendar` | `value` | `defaultValue` |
| `DateWheelPicker` | `value` | `defaultValue` (default: today) |
| `TimeRangePicker`, `DateTimePicker`, `DurationPicker`, `MonthPicker`, `WeekStrip`, `ColorPicker`, `Slider`, `Rating`, `InputOTP`, `PhoneField` | `value` | `defaultValue` |
| `EmojiPicker` skin tone | `skinTone` | `defaultSkinTone` |
| `EmojiPicker` recents | `recent` | `defaultRecent` |
| `Select` / `SelectList` / `CountryPicker` / `TimeZonePicker` | `value` | — (always controlled) |
| `SegmentedControl`, `ChipGroup` | `value` | — (always controlled) |

:::caution Select is controlled-only
`Select` and `SelectList` don't keep their own selection. Always pass `value` and update it in `onValueChange`.
:::

Setting `value` from outside (for example, a "Reset" button) moves the component **without** firing `onValueChange`. `onValueChange` only reports changes the user made.

## `onValueChange` vs `onValueChanging`

Wheel-based pickers (`WheelPicker`, `MultiWheelPicker` columns, `TimePicker`, `DateWheelPicker`, `DateTimePicker`, `DurationPicker`) and `Slider` fire two callbacks:

| Callback | When | Use it for |
| --- | --- | --- |
| `onValueChange` | Once, after the wheel **settles** on a new value, or the slider is let go | Updating state, saving |
| `onValueChanging` | On **every row crossing** while scrolling, or every step while dragging | Haptics, live previews |

```tsx
<WheelPicker
  items={items}
  value={value}
  onValueChange={setValue}
  onValueChanging={() => Haptics.selectionAsync()}
/>
```

## Sheets and drafts

Every picker sheet (`DatePickerSheet`, `TimePickerSheet`, `WheelPickerSheet` and the others) wraps a picker in a [`BottomSheet`](../components/bottom-sheet) with **Cancel** and **Done**:

- The sheet copies `value` into a **draft** each time it opens.
- Scrolling or tapping changes only the draft.
- **Done** calls `onConfirm(draft)`, then `onClose()`.
- **Cancel**, a backdrop tap, a swipe down or Android back calls `onClose()` only, so the draft is discarded.

```tsx
<TimePickerSheet open={open} onOpenChange={setOpen} value={time} onConfirm={setTime} />
```

`EmojiPickerSheet` has no Done button: picking an emoji calls `onSelect` and (by default) closes the sheet. `Select` opens its own sheet; you don't manage `visible`.

## Fields

In a form, the picker hides behind a field. `Select` is one, and every sheet has a field version that takes the same props without `visible` / `onClose`: [`DatePickerField`, `TimePickerField`, `DateTimePickerField`, `WheelPickerField`, `EmojiPickerField`](../components/picker-fields), and `TimeRangePickerField`, `DurationPickerField`, `MonthPickerField` and `ColorPickerField`. The field owns the open state, shows the confirmed value formatted for `locale`, and looks the same as `Select`'s field. By default it opens a bottom sheet on iOS and Android and a dropdown under the field on the web; `presentation` picks `'bottomSheet'`, `'modal'`, `'dropdown'` or `'inline'` (expanded in place under the field).

```tsx
<TimePickerField label="Alarm" value={time} onConfirm={setTime} />
```

## Designs

Pickers look native wherever they run: the iOS design on iOS, Material Design on Android, a web design in the browser. The design sets shapes and layout (where Done sits, a radio or a ✓, wheels or a clock dial), never your colors. Use one look everywhere, or for one component, with `design`:

```tsx
<PatineProvider design="ios">{/* the iOS look on Android and the web too */}</PatineProvider>
<TimePicker design="material" value={time} onValueChange={setTime} />
```

→ [Designs guide](../guides/designs)

## Theming

Three layers, each merged on top of the previous one:

1. Built-in `lightTheme` / `darkTheme`, chosen from the OS appearance, with the [design](../guides/designs)'s shapes
2. `<PatineProvider theme={…} darkTheme={…}>` for your whole app
3. The `theme` prop on any single component

```tsx
<PatineProvider theme={{ colors: { primary: '#0EA5E9' }, radius: { md: 6 } }}>
  <DatePicker theme={{ colors: { primary: '#22C55E' } }} />  {/* green only here */}
</PatineProvider>
```

→ [Theming guide](../guides/theming)

## Slot styles

Every visual part of a component has a named **slot**. Pass styles for any of them through `styles`:

```tsx
<DatePicker
  styles={{
    selectedDay: { borderRadius: 8 },
    headerTitle: { fontSize: 20 },
    rangeBand: { backgroundColor: '#FFE4E6' },
  }}
/>
```

Slot names are typed, so your editor autocompletes them. Each component page lists its slots. → [Styling guide](../guides/styling)

## Render props

When styles aren't enough, replace a part entirely:

| Component | Render props |
| --- | --- |
| `WheelPicker` | `renderItem`, `renderIndicator` |
| `DatePicker` / `Calendar` | `renderDay`, `renderArrow`, `formatTitle` |
| `Select` / `SelectList` | `renderTrigger`, `renderOption`, `renderGroupHeader`, `renderLoading` |
| `SegmentedControl`, `ChipGroup` | `renderItem`, `renderArrow` |
| `Rating` | `renderIcon` |
| `EmojiPicker` | `renderEmoji`, `categoryIcons` |
| `*PickerField` / `PickerField` | `renderTrigger`, `renderChevron` |

→ [Render props guide](../guides/render-props)

## Strings and i18n

No component hard-codes a user-facing string you can't change. Done, Cancel, placeholders, search hints, empty states and category labels are all props. Month, weekday and AM/PM names come from `Intl` for whatever `locale` you pass. → [i18n & RTL](../guides/i18n-rtl)
