# Rivier UI > A component library for AI-native development: React components you copy into a project and own, themed > from one place (light or dark, square to round, any highlight colour), covering controls, layout and bento > grids, motion and transitions, 3D and charts, dates, flows, conversation, media. Built on Radix, Tailwind CSS, > Motion and three.js. Keyboard operable, right-to-left safe, no fixed words: labels are props. Install an item into a project: `rivier-ui add ` (it brings what the item depends on, and the theme). Imports in a project: `@/components//` and `@/lib/cn`. Rules for using and writing components: CONVENTIONS.md. Theming: registry/theme/rivier-ui.css. ## Helpers ### announce Says a message to screen-reader users through one shared live region, politely or at once, without moving focus. Use it: Something changed that a sighted person can see but no focus change will read out: an item was moved, a filter applied, a total changed, a reply finished. Not for content the person is about to read anyway, and not for errors on a field (use the field's own message). A component that is already a live region (status-line, toaster) does not need it. ```tsx announce("Lunch moved to position 2 of 5"); announce("The connection was lost", "assertive"); ``` ### cn Joins class names and resolves Tailwind conflicts, so a class passed in wins over a component's own. Use it: Every component uses it. Use it wherever classes are combined conditionally. ```tsx cn("px-4 py-2", isActive && "bg-primary", className) ``` ### direction Tells whether an element reads right to left, and turns "start" and "end" arrow keys and offsets the right way round for it. Use it: A component handles Left and Right arrow keys, or moves something sideways with a transform, and must work in right-to-left pages. Layout itself needs no code: use logical utilities (ps-, ms-, start-, text-start). To set a direction for part of a page use direction-provider. ```tsx function onKeyDown(event: KeyboardEvent) { const step = inlineStep(event.key, event.currentTarget); // +1 towards the end, -1 towards the start, 0 otherwise if (step !== 0) move(step); } ``` ### motion The motion tokens as numbers for the motion package (easing, durations, a pointer spring), the useMotionSafe gate, and the entrance engine the reveal components share. Use it: Any component animated with the motion package: take timing from here so it matches the CSS tokens, and gate on useMotionSafe so server markup is the final state. For CSS transitions use the duration-* and ease-out utilities instead. ```tsx const safe = useMotionSafe(); return ( ); ``` ### theme-color Resolves a theme CSS variable such as "--highlight" to an rgb() string that three.js and canvas code can parse, and re-reads it when the theme changes. Use it: Anything that cannot use a Tailwind class or `var()`: three.js materials, canvas drawing. In markup use the token classes (`bg-primary`, `fill-chart-1`) instead. ```tsx const { "--highlight": highlight, "--foreground": ink } = useThemeColors(["--highlight", "--foreground"]); material.color.set(highlight); // Outside React: const border = readThemeColor("--border"); ``` ### use-controllable-state State that a parent may control: it follows `value` when one is given and keeps its own from `defaultValue` when not, calling `onChange` either way. Use it: Writing a component that should work both controlled (`value` + `onValueChange`) and uncontrolled (`defaultValue`), which every input-like component in the library does. Radix primitives already do this for their own state; use this for state the library adds on top. ```tsx function Stepper({ value, defaultValue = 0, onValueChange }: { value?: number; defaultValue?: number; onValueChange?: (value: number) => void }) { const [count, setCount] = useControllableState({ value, defaultValue, onChange: onValueChange }); return ; } ``` ### use-media Follows an audio or video element (playing, time, duration, buffered, volume, rate, text tracks, waiting, error) as React state, with the actions to drive it, the context player parts share, and time formatting through Intl. Use it: Building player parts around a `