# Using Detent in a React project

Implement the interaction requested by the user using Detent. First inspect the project's framework, React version, package manager, existing components and styling conventions. Ask for the intended interaction if it is unclear.

## Authoritative references

- Documentation and API: https://detent.hayder.sh/docs
- Working examples and their source: https://detent.hayder.sh/examples
- Live visual configuration: https://detent.hayder.sh/playground
- Source and issues: https://github.com/hayderkg/detent

Read the documentation and the installed TypeScript declarations before selecting props. The package is pre-release; the installed version's types take precedence if the website documents a newer API. Do not invent props or exports.

## Install and choose an entry

Install `detent` with the project's package manager. React 18 and 19 are supported. Import only the entry needed:

- `import { Detent } from 'detent'`: a styled, interactive wheel picker. Start here for choosing a value.
- `import { useDetent } from 'detent'`: the headless hook when custom markup or geometry is necessary.
- `import { DetentText } from 'detent/text'`: changing short, single-line interface labels. Pass the current label as children. Matching graphemes stay in place by default; `morph={false}` rolls the whole label.
- `import { DetentNumber } from 'detent/number'`: formatted, rolling numbers. Pass a numeric `value`, explicit `locales` and optional `format` options for `Intl.NumberFormat`.
- `import { ticks } from 'detent/feedback'`: optional sound and haptics. Create the handler once, outside render or with useMemo.

Do not build animated numbers with an interactive picker per digit when DetentNumber fits. Do not add gesture handlers to text or number displays.

## Integration

A controlled picker uses `items`, `value`, `onChange` and an accessible `label`. Use `defaultValue` for an uncontrolled picker. For objects, provide stable `getKey` and meaningful `getLabel` functions; selected values are item keys, not the objects themselves. Check the installed types for key and callback shapes.

`onChange` fires when the picker settles by default. Use `changeOn="tick"` only when the application needs updates during motion. Keep frame-by-frame visual effects outside React state using the hook's `subscribe` API.

In Next.js, put stateful wrappers in a client component with `'use client'`. Preserve server rendering; do not disable SSR as a workaround. For DetentNumber, use the same numeric value, explicit locale and formatting options on server and client to avoid hydration differences.

For a headless picker, spread the supplied root, track and row props, render each row with its provided key, and include `getLiveRegionProps()` on a visually hidden sibling outside the listbox. Preserve the library's keyboard and ARIA behavior.

Text and number components inherit typography and respect reduced motion. Keep their layout compatible with the documented animated layer. DetentNumber supports `classNames` for integer, fraction, decimal, group, currency, sign and unit parts. There is no continuous carry mode; do not invent a `continuous` prop. RTL/bidirectional text and unsupported layouts fall back to native updates without rolling.

For forms, use the picker’s documented `name` support. Disabled pickers are not submitted. Native constraint validation does not apply to the hidden form input.

## Verify

Preserve the project's visual language and limit animation to meaningful changes. Check keyboard interaction, focus visibility, accessible labels, mobile layout, reduced motion, controlled updates and console errors. Verify server/client formatting when SSR is used. Run the project's relevant type checks and tests, and report any unverified behavior.