rudiment-ui 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (186) hide show
  1. package/README.md +59 -21
  2. package/dist/components/Alert/Alert.d.ts +28 -1
  3. package/dist/components/Alert/Alert.d.ts.map +1 -1
  4. package/dist/components/AppShell/AppShell.d.ts +52 -6
  5. package/dist/components/AppShell/AppShell.d.ts.map +1 -1
  6. package/dist/components/Avatar/Avatar.d.ts +21 -1
  7. package/dist/components/Avatar/Avatar.d.ts.map +1 -1
  8. package/dist/components/Badge/Badge.d.ts +23 -0
  9. package/dist/components/Badge/Badge.d.ts.map +1 -1
  10. package/dist/components/Brand/Brand.d.ts +17 -2
  11. package/dist/components/Brand/Brand.d.ts.map +1 -1
  12. package/dist/components/Breadcrumb/Breadcrumb.d.ts +24 -2
  13. package/dist/components/Breadcrumb/Breadcrumb.d.ts.map +1 -1
  14. package/dist/components/Button/Button.d.ts +31 -0
  15. package/dist/components/Button/Button.d.ts.map +1 -1
  16. package/dist/components/Card/Card.d.ts +34 -0
  17. package/dist/components/Card/Card.d.ts.map +1 -1
  18. package/dist/components/Charts/BarChart/BarChart.d.ts +39 -4
  19. package/dist/components/Charts/BarChart/BarChart.d.ts.map +1 -1
  20. package/dist/components/Charts/DonutChart/DonutChart.d.ts +31 -0
  21. package/dist/components/Charts/DonutChart/DonutChart.d.ts.map +1 -1
  22. package/dist/components/Charts/LineChart/LineChart.d.ts +52 -6
  23. package/dist/components/Charts/LineChart/LineChart.d.ts.map +1 -1
  24. package/dist/components/Charts/Sparkline/Sparkline.d.ts +35 -0
  25. package/dist/components/Charts/Sparkline/Sparkline.d.ts.map +1 -0
  26. package/dist/components/Checkbox/Checkbox.d.ts +26 -3
  27. package/dist/components/Checkbox/Checkbox.d.ts.map +1 -1
  28. package/dist/components/Checkbox/CheckboxGroup.d.ts +20 -0
  29. package/dist/components/Checkbox/CheckboxGroup.d.ts.map +1 -1
  30. package/dist/components/CircularProgress/CircularProgress.d.ts +33 -0
  31. package/dist/components/CircularProgress/CircularProgress.d.ts.map +1 -1
  32. package/dist/components/ComboBox/ComboBox.d.ts +29 -4
  33. package/dist/components/ComboBox/ComboBox.d.ts.map +1 -1
  34. package/dist/components/DatePicker/DatePicker.d.ts +30 -2
  35. package/dist/components/DatePicker/DatePicker.d.ts.map +1 -1
  36. package/dist/components/DatePicker/DateRangePicker.d.ts +26 -1
  37. package/dist/components/DatePicker/DateRangePicker.d.ts.map +1 -1
  38. package/dist/components/DatePicker/dateUtils.d.ts +1 -0
  39. package/dist/components/DatePicker/dateUtils.d.ts.map +1 -1
  40. package/dist/components/DescriptionList/DescriptionList.d.ts +44 -0
  41. package/dist/components/DescriptionList/DescriptionList.d.ts.map +1 -0
  42. package/dist/components/Dialog/Dialog.d.ts +39 -0
  43. package/dist/components/Dialog/Dialog.d.ts.map +1 -1
  44. package/dist/components/Divider/Divider.d.ts +18 -5
  45. package/dist/components/Divider/Divider.d.ts.map +1 -1
  46. package/dist/components/Dot/Dot.d.ts +22 -8
  47. package/dist/components/Dot/Dot.d.ts.map +1 -1
  48. package/dist/components/EmptyState/EmptyState.d.ts +23 -2
  49. package/dist/components/EmptyState/EmptyState.d.ts.map +1 -1
  50. package/dist/components/Form/Form.d.ts +20 -1
  51. package/dist/components/Form/Form.d.ts.map +1 -1
  52. package/dist/components/Icon/Icon.d.ts +17 -0
  53. package/dist/components/Icon/Icon.d.ts.map +1 -1
  54. package/dist/components/IconButton/IconButton.d.ts +24 -0
  55. package/dist/components/IconButton/IconButton.d.ts.map +1 -1
  56. package/dist/components/Image/Image.d.ts +31 -6
  57. package/dist/components/Image/Image.d.ts.map +1 -1
  58. package/dist/components/Input/Input.d.ts +32 -0
  59. package/dist/components/Input/Input.d.ts.map +1 -1
  60. package/dist/components/Kanban/KanbanBoard.d.ts +32 -0
  61. package/dist/components/Kanban/KanbanBoard.d.ts.map +1 -1
  62. package/dist/components/Kanban/KanbanCard.d.ts +12 -1
  63. package/dist/components/Kanban/KanbanCard.d.ts.map +1 -1
  64. package/dist/components/Kanban/KanbanColumn.d.ts +13 -0
  65. package/dist/components/Kanban/KanbanColumn.d.ts.map +1 -1
  66. package/dist/components/Kanban/KanbanOverlayContext.d.ts +7 -0
  67. package/dist/components/Kanban/KanbanOverlayContext.d.ts.map +1 -0
  68. package/dist/components/Kanban/kanbanMoves.d.ts +18 -0
  69. package/dist/components/Kanban/kanbanMoves.d.ts.map +1 -0
  70. package/dist/components/Link/Link.d.ts +24 -3
  71. package/dist/components/Link/Link.d.ts.map +1 -1
  72. package/dist/components/Menu/Keyboard.d.ts +9 -0
  73. package/dist/components/Menu/Keyboard.d.ts.map +1 -1
  74. package/dist/components/Menu/Menu.d.ts +13 -0
  75. package/dist/components/Menu/Menu.d.ts.map +1 -1
  76. package/dist/components/Menu/MenuItem.d.ts +11 -0
  77. package/dist/components/Menu/MenuItem.d.ts.map +1 -1
  78. package/dist/components/Menu/MenuSection.d.ts +12 -0
  79. package/dist/components/Menu/MenuSection.d.ts.map +1 -1
  80. package/dist/components/Menu/MenuSeparator.d.ts +8 -0
  81. package/dist/components/Menu/MenuSeparator.d.ts.map +1 -1
  82. package/dist/components/Menu/MenuTrigger.d.ts +16 -0
  83. package/dist/components/Menu/MenuTrigger.d.ts.map +1 -1
  84. package/dist/components/Menu/SubmenuTrigger.d.ts +13 -0
  85. package/dist/components/Menu/SubmenuTrigger.d.ts.map +1 -1
  86. package/dist/components/NavItem/NavItem.d.ts +14 -0
  87. package/dist/components/NavItem/NavItem.d.ts.map +1 -1
  88. package/dist/components/NumberField/NumberField.d.ts +36 -3
  89. package/dist/components/NumberField/NumberField.d.ts.map +1 -1
  90. package/dist/components/PageHeader/PageHeader.d.ts +18 -1
  91. package/dist/components/PageHeader/PageHeader.d.ts.map +1 -1
  92. package/dist/components/Pagination/Pagination.d.ts +19 -2
  93. package/dist/components/Pagination/Pagination.d.ts.map +1 -1
  94. package/dist/components/ProgressBar/ProgressBar.d.ts +36 -2
  95. package/dist/components/ProgressBar/ProgressBar.d.ts.map +1 -1
  96. package/dist/components/RadioGroup/Radio.d.ts +6 -1
  97. package/dist/components/RadioGroup/Radio.d.ts.map +1 -1
  98. package/dist/components/RadioGroup/RadioGroup.d.ts +24 -0
  99. package/dist/components/RadioGroup/RadioGroup.d.ts.map +1 -1
  100. package/dist/components/Rating/Rating.d.ts +26 -6
  101. package/dist/components/Rating/Rating.d.ts.map +1 -1
  102. package/dist/components/RouterProvider/RouterProvider.d.ts +1 -0
  103. package/dist/components/RouterProvider/RouterProvider.d.ts.map +1 -1
  104. package/dist/components/SectionHeader/SectionHeader.d.ts +14 -1
  105. package/dist/components/SectionHeader/SectionHeader.d.ts.map +1 -1
  106. package/dist/components/Select/Option.d.ts +8 -0
  107. package/dist/components/Select/Option.d.ts.map +1 -1
  108. package/dist/components/Select/Select.d.ts +29 -0
  109. package/dist/components/Select/Select.d.ts.map +1 -1
  110. package/dist/components/StatCard/StatCard.d.ts +23 -1
  111. package/dist/components/StatCard/StatCard.d.ts.map +1 -1
  112. package/dist/components/Stepper/Stepper.d.ts +34 -2
  113. package/dist/components/Stepper/Stepper.d.ts.map +1 -1
  114. package/dist/components/Switch/Switch.d.ts +13 -0
  115. package/dist/components/Switch/Switch.d.ts.map +1 -1
  116. package/dist/components/Table/Table.d.ts +31 -3
  117. package/dist/components/Table/Table.d.ts.map +1 -1
  118. package/dist/components/Table/TableBody.d.ts +7 -0
  119. package/dist/components/Table/TableBody.d.ts.map +1 -1
  120. package/dist/components/Table/TableCell.d.ts +11 -0
  121. package/dist/components/Table/TableCell.d.ts.map +1 -1
  122. package/dist/components/Table/TableColumn.d.ts +16 -1
  123. package/dist/components/Table/TableColumn.d.ts.map +1 -1
  124. package/dist/components/Table/TableHeader.d.ts +8 -1
  125. package/dist/components/Table/TableHeader.d.ts.map +1 -1
  126. package/dist/components/Table/TableRow.d.ts +10 -1
  127. package/dist/components/Table/TableRow.d.ts.map +1 -1
  128. package/dist/components/Tabs/Tab.d.ts +8 -0
  129. package/dist/components/Tabs/Tab.d.ts.map +1 -1
  130. package/dist/components/Tabs/TabList.d.ts +15 -1
  131. package/dist/components/Tabs/TabList.d.ts.map +1 -1
  132. package/dist/components/Tabs/TabPanel.d.ts +9 -0
  133. package/dist/components/Tabs/TabPanel.d.ts.map +1 -1
  134. package/dist/components/Tabs/Tabs.d.ts +11 -1
  135. package/dist/components/Tabs/Tabs.d.ts.map +1 -1
  136. package/dist/components/Tag/Tag.d.ts +27 -0
  137. package/dist/components/Tag/Tag.d.ts.map +1 -1
  138. package/dist/components/Textarea/Textarea.d.ts +43 -0
  139. package/dist/components/Textarea/Textarea.d.ts.map +1 -1
  140. package/dist/components/Toast/Toast.d.ts +17 -3
  141. package/dist/components/Toast/Toast.d.ts.map +1 -1
  142. package/dist/components/Toast/toastQueue.d.ts +20 -1
  143. package/dist/components/Toast/toastQueue.d.ts.map +1 -1
  144. package/dist/components/Tooltip/Tooltip.d.ts +32 -0
  145. package/dist/components/Tooltip/Tooltip.d.ts.map +1 -1
  146. package/dist/components/TopBar/TopBar.d.ts +17 -2
  147. package/dist/components/TopBar/TopBar.d.ts.map +1 -1
  148. package/dist/components.json +7919 -0
  149. package/dist/hooks/useChartTheme.d.ts +10 -0
  150. package/dist/hooks/useChartTheme.d.ts.map +1 -1
  151. package/dist/hooks/useLoadingButton.d.ts +10 -0
  152. package/dist/hooks/useLoadingButton.d.ts.map +1 -1
  153. package/dist/index.css +1 -1
  154. package/dist/index.d.ts +11 -0
  155. package/dist/index.d.ts.map +1 -1
  156. package/dist/index.js +1858 -1621
  157. package/dist/layouts/Box/Box.d.ts +31 -1
  158. package/dist/layouts/Box/Box.d.ts.map +1 -1
  159. package/dist/layouts/Center/Center.d.ts +22 -0
  160. package/dist/layouts/Center/Center.d.ts.map +1 -1
  161. package/dist/layouts/Cluster/Cluster.d.ts +19 -0
  162. package/dist/layouts/Cluster/Cluster.d.ts.map +1 -1
  163. package/dist/layouts/Cover/Cover.d.ts +28 -0
  164. package/dist/layouts/Cover/Cover.d.ts.map +1 -1
  165. package/dist/layouts/Grid/Grid.d.ts +18 -0
  166. package/dist/layouts/Grid/Grid.d.ts.map +1 -1
  167. package/dist/layouts/Sidebar/Sidebar.d.ts +29 -0
  168. package/dist/layouts/Sidebar/Sidebar.d.ts.map +1 -1
  169. package/dist/layouts/Stack/Stack.d.ts +21 -2
  170. package/dist/layouts/Stack/Stack.d.ts.map +1 -1
  171. package/dist/layouts/Switcher/Switcher.d.ts +19 -0
  172. package/dist/layouts/Switcher/Switcher.d.ts.map +1 -1
  173. package/dist/llms-full.txt +2284 -0
  174. package/dist/llms.txt +162 -0
  175. package/dist/typography/Heading/Heading.d.ts +12 -0
  176. package/dist/typography/Heading/Heading.d.ts.map +1 -1
  177. package/dist/typography/Prose/Prose.d.ts +21 -0
  178. package/dist/typography/Prose/Prose.d.ts.map +1 -1
  179. package/dist/typography/Text/Text.d.ts +28 -1
  180. package/dist/typography/Text/Text.d.ts.map +1 -1
  181. package/dist/utils/cn.d.ts +7 -0
  182. package/dist/utils/cn.d.ts.map +1 -1
  183. package/mcp/README.md +111 -0
  184. package/mcp/render.mjs +116 -0
  185. package/mcp/server.mjs +321 -0
  186. package/package.json +12 -2
@@ -0,0 +1,2284 @@
1
+ # rudiment-ui 0.6.0
2
+
3
+ > Accessible React 19 component library built on React Aria. Styled with BEM classes and `--rudi-*` CSS custom properties (design tokens). It does not use Tailwind classes. Eight themes are switched with `data-theme`.
4
+
5
+ This file is generated from the package's TypeScript source and JSDoc (`scripts/component-docs.mjs`), so it matches the installed version. `llms.txt` holds the conventions and an index. `llms-full.txt` adds every component's props, defaults taken from the implementation, compound parts and examples. `components.json` holds the same data as JSON and adds types and descriptions for the props inherited from React Aria. The `.d.ts` files carry the same JSDoc for editor hovers.
6
+
7
+ ## Setup
8
+
9
+ ```tsx
10
+ // Once, at the app entry (main.tsx, app/layout.tsx, …)
11
+ import 'rudiment-ui/styles'
12
+
13
+ import { RudiButton, RudiInput, RudiStack } from 'rudiment-ui'
14
+ ```
15
+
16
+ - No provider is required. `RudiDialog` portals itself. Mount `RudiToastRegion` once if you use `rudiToast`. Wrap the app in `RudiRouterProvider` for client-side routing with links.
17
+ - Every export is marked `'use client'`, so you can import it directly from a Next.js App Router Server Component.
18
+ - The stylesheet has no CSS reset and no bare-element selectors, so it won't change your app's own styles.
19
+
20
+ ## Conventions (read before writing code)
21
+
22
+ - **Every export is prefixed `Rudi`**: `RudiButton`, `RudiButtonProps`. The only exceptions are `rudiToast`, `cn`, `useChartTheme` and `useLoadingButton`.
23
+ - **`onPress`, not `onClick`.** Interactive components use React Aria press events, which cover mouse, touch and keyboard.
24
+ - **`onChange` receives a value, not an event**: `RudiInput` passes a `string`, `RudiCheckbox` a `boolean`, `RudiCheckboxGroup` a `string[]`, `RudiNumberField` a `number | null`, and `RudiDatePicker` an ISO `string | null`.
25
+ - **State props use React Aria names**: `isDisabled`, `isRequired`, `isReadOnly`, `isSelected`, `isOpen`, `selectedKey`, `onSelectionChange`. Don't use the HTML `disabled`/`checked` attributes.
26
+ - **`label` is a required string prop**, not children, on the form fields (`RudiInput`, `RudiTextarea`, `RudiSelect`, `RudiComboBox`, `RudiRadioGroup`, `RudiCheckboxGroup`, `RudiNumberField`, the date pickers), on progress indicators and on charts. It is the accessible name. Validation text goes in `errorMessage`, which also sets the invalid state.
27
+ - **Icons are Iconify name strings**: `icon="mdi:close"` or `iconBefore="lucide:plus"`. Never import icon components.
28
+ - **`className` is merged** with the component's own classes (`clsx` + `tailwind-merge`), never replaced. To change how something looks, override tokens instead of piling on classes.
29
+ - **Compound components use dot parts**: `RudiCard.Header`, `RudiDialog.Footer`, `RudiAppShell.Sidebar`, `RudiCover.Centered`.
30
+ - **Collections use React Aria's pattern**: `items` plus a render function that returns `RudiOption`, `RudiMenuItem` or `RudiTableRow`, or static children with `id`s.
31
+ - **Layout and typography primitives** (`RudiBox`, `RudiStack`, `RudiCluster`, `RudiGrid`, `RudiSidebar`, `RudiCenter`, `RudiCover`, `RudiSwitcher`, `RudiText`, `RudiProse`) take an `as` prop and spread any DOM attribute. `RudiHeading` spreads DOM attributes too, but its `level` prop picks the tag. Their spacing props take **CSS length strings** (`"1rem"`, `"var(--rudi-spacing-6)"`), not a numeric scale. The spacing prop is always named `space`; on `RudiBox` it is `padding`. Most other components have closed prop interfaces. The reference notes each one that spreads DOM props.
32
+ - **Prefer the primitives over hand-written layout CSS**: use `RudiStack` for vertical rhythm, `RudiCluster` for wrapping inline groups, `RudiGrid` for responsive cards, `RudiSidebar` for a fixed side plus fluid content, `RudiSwitcher` for a row that becomes a column, and `RudiCenter` for a max-width column.
33
+
34
+ ## Themes
35
+
36
+ Set `data-theme` on `<html>` or on any wrapper to theme a subtree. The default theme lives on `:root`, so leave the attribute off for it. There is no `"light"` value.
37
+
38
+ `dark`, `roomy`, `roomy-dark`, `soft`, `soft-dark`, `compressed`, `compressed-dark`, `auto`. `auto` follows the OS `prefers-color-scheme`.
39
+
40
+ ## Tokens
41
+
42
+ Every visual value is a `--rudi-*` custom property in three tiers: primitive (`--rudi-color-neutral-900`), then semantic (`--rudi-color-brand-primary`), then component (`--rudi-component-button-primary-bg`). Override the semantic tier in a stylesheet loaded after `rudiment-ui/styles`. Theme blocks have the same specificity as `:root` and come later in the cascade, so repeat each override under every `[data-theme="…"]` you use.
43
+
44
+ Common semantic tokens:
45
+ - `--rudi-color-brand-primary` (with `-hover` and `-active`)
46
+ - `--rudi-color-background-{surface,raised,sunken,overlay}`
47
+ - `--rudi-color-text-{default,subtle,disabled}`
48
+ - `--rudi-color-border-{default,focus,error}`
49
+ - `--rudi-color-feedback-{error,success,warning,info}`
50
+ - `--rudi-spacing-{0,1,2,3,4,6,8,12}`
51
+ - `--rudi-radius-{none,sm,md,lg,full}`
52
+ - `--rudi-font-size-{xs…4xl}`
53
+
54
+ ## Reading the prop reference (llms-full.txt)
55
+
56
+ - Each component's table lists the props it declares itself. **Required** props are marked, and a default comes from the implementation.
57
+ - "Inherited from React Aria" lists the extra props the component forwards, such as `onPress`, `isDisabled` and `aria-label`. React Aria documents their meaning, and `components.json` has their types.
58
+ - "`ref` forwards to …" names the DOM element a `ref` reaches.
59
+
60
+ ## Component index
61
+
62
+ - `RudiButton` — A text button built on React Aria's `useButton`.
63
+ - `RudiInput` — A single-line text field with label, description and error message.
64
+ - `RudiCheckbox` — A checkbox with a visible label.
65
+ - `RudiCheckboxGroup` — A labelled set of `RudiCheckbox` options whose selection is a string array.
66
+ - `RudiSelect` — A dropdown for choosing one option from a list.
67
+ - `RudiOption` — One entry in a `RudiSelect` or `RudiComboBox` list.
68
+ - `RudiMenuTrigger` — Connects a pressable trigger to a `RudiMenu`.
69
+ - `RudiMenu` — The popover and item list of a menu.
70
+ - `RudiMenuItem` — A single action in a `RudiMenu`.
71
+ - `RudiMenuSection` — Groups related `RudiMenuItem`s inside a `RudiMenu`, with an optional `title` heading.
72
+ - `RudiMenuSeparator` — Horizontal divider between groups of items in a `RudiMenu`.
73
+ - `RudiKeyboard` — Keyboard shortcut hint, styled as the trailing shortcut text of a menu item.
74
+ - `RudiSubmenuTrigger` — Nests a menu inside a `RudiMenu`.
75
+ - `RudiSeparator` — React Aria's `Separator`, re-exported unchanged and unstyled.
76
+ - `RudiDialog` — Modal dialog with a title, scrolling body and optional pinned footer.
77
+ - `RudiDialog.Footer` — Action row pinned to the bottom of the dialog; primary action last.
78
+ - `RudiSwitch` — An on/off toggle for settings that take effect immediately; use `RudiCheckbox` for choices submitted with a form.
79
+ - `RudiRadioGroup` — A labelled set of mutually exclusive `RudiRadio` options.
80
+ - `RudiRadio` — A single option inside `RudiRadioGroup`.
81
+ - `RudiTooltipTrigger` — Shows a `RudiTooltip` when its trigger is hovered or focused.
82
+ - `RudiTooltip` — Tooltip bubble.
83
+ - `RudiAlert` — Inline message banner for status, feedback, or warnings that sit within the page content.
84
+ - `RudiIconButton` — A button that shows only an icon.
85
+ - `RudiBadge` — Small non-interactive label for status or counts.
86
+ - `RudiTag` — Compact label for a keyword, filter, or selection.
87
+ - `RudiIcon` — Renders an Iconify icon by name (for example `"mdi:close"`).
88
+ - `RudiCard` — Surface container that groups related content.
89
+ - `RudiCard.Header` — Top section of the card; holds the title and actions.
90
+ - `RudiCard.Body` — Main content area of the card.
91
+ - `RudiCard.Footer` — Bottom section of the card; holds buttons or metadata.
92
+ - `RudiProgressBar` — Horizontal bar showing determinate progress.
93
+ - `RudiDivider` — Thin rule that separates sections of content.
94
+ - `RudiDot` — Small colored circle for status or category.
95
+ - `RudiLink` — Styled anchor for navigation.
96
+ - `RudiImage` — Image in a framed, rounded container with an optional aspect ratio and overlay layer.
97
+ - `RudiRating` — Star rating display that becomes an input when `onChange` is provided.
98
+ - `RudiStepper` — Ordered list of steps that shows progress through a multi-step process.
99
+ - `RudiTextarea` — A multi-line text field with label, description and error message.
100
+ - `RudiBreadcrumb` — Navigation trail showing where the current page sits in a hierarchy.
101
+ - `RudiPagination` — Page navigation with previous and next buttons and numbered pages, truncated with ellipses for long ranges.
102
+ - `RudiAvatar` — Circular representation of a person or entity: an image when `src` loads, otherwise initials derived from `name`.
103
+ - `RudiStatCard` — Outlined card showing one headline metric with an optional change indicator.
104
+ - `RudiNavItem` — Navigation entry for a sidebar: an `a` when `href` is set, otherwise a `button`.
105
+ - `RudiCircularProgress` — Ring showing determinate progress, with optional content in the center.
106
+ - `RudiBarChart` — Bar chart with one series per data key, built on Recharts and the library chart theme.
107
+ - `RudiLineChart` — Line chart with one series per data key, built on Recharts and the library chart theme.
108
+ - `RudiSparkline` — Tiny axis-less line for showing a trend inside a card, table cell, or sentence.
109
+ - `RudiDonutChart` — Donut chart showing parts of a whole, built on Recharts and the library chart theme.
110
+ - `RudiKanbanBoard` — Drag-and-drop board of columns and cards, with pointer and keyboard dragging and screen-reader announcements.
111
+ - `RudiKanbanBoard.Column` — A single column.
112
+ - `RudiKanbanColumn` — One droppable column of sortable cards.
113
+ - `RudiKanbanCard` — A draggable card with a drag handle.
114
+ - `RudiHeading` — Semantic heading (`h1` to `h6`) whose visual size is set separately from its level, so the document outline stays correct while the look follows the design.
115
+ - `RudiText` — Body-level text in one of five variants (body, body-sm, caption, overline, code).
116
+ - `RudiProse` — Wrapper that styles plain HTML children (paragraphs, headings, lists, links) with consistent typography and vertical rhythm.
117
+ - `RudiBox` — Padded container with an optional border or inverted surface.
118
+ - `RudiStack` — Vertical list of children with consistent spacing.
119
+ - `RudiCluster` — Horizontal row of items that wraps onto new lines when space runs out.
120
+ - `RudiGrid` — Responsive grid of equal-width columns that adds or drops columns as the container width changes, with no breakpoints.
121
+ - `RudiSidebar` — Two-panel layout where one panel has a set width and the other fills the rest, wrapping to a column when the content would drop below `contentMin`.
122
+ - `RudiCenter` — Horizontally centers its content in a column capped at a maximum width.
123
+ - `RudiCover` — Full-height column that pins an optional first and last child to the top and bottom and centers `RudiCover.Centered` in between. Use it for hero sections and login pages; use `RudiCenter` for horizontal centering only. Polymorphic through `as`; unrecognised DOM props (`id`, `aria-*`, `data-*`, handlers) are spread onto the root element, and `className` is merged with the built-in class, not replaced.
124
+ - `RudiCover.Centered` — The child centered vertically between the cover's other children.
125
+ - `RudiSwitcher` — Row of children that switches to a single column, all at once, when the container is narrower than `threshold`.
126
+ - `RudiAppShell` — Application frame with a sidebar and a content area; below 900px the sidebar becomes a drawer that Escape and the backdrop close.
127
+ - `RudiAppShell.Sidebar` — Navigation drawer (an `aside`) shown inline on wide screens and as a slide-over below 900px; renders its own backdrop.
128
+ - `RudiAppShell.Content` — Column beside the sidebar that holds the top bar and the main area.
129
+ - `RudiAppShell.Main` — The page's `main` landmark; centers its children in a padded column with a max width.
130
+ - `RudiAppShell.MenuButton` — Hamburger button that toggles the sidebar drawer; place it in the top bar's `start` slot.
131
+ - `RudiTopBar` — Horizontal application bar with start, center, and end slots and an optional announcement strip above.
132
+ - `RudiDescriptionList` — Semantic `dl` for read-only key-value data such as record details.
133
+ - `RudiPageHeader` — Title block for a page: heading with optional eyebrow, subtitle, metadata, and an actions slot.
134
+ - `RudiSectionHeader` — Heading row for a section of a page, with an optional description and an action slot.
135
+ - `RudiRouterProvider` — Connects Rudi links (`RudiLink`, `RudiNavItem`, `RudiBreadcrumb`) to your router for client-side navigation.
136
+ - `RudiBrand` — Logo lockup: a mark plus the product name, optionally linking home.
137
+ - `RudiForm` — A `<form>` that collects submitted values as `FormData`, never reloads the page, and shows a focusable error summary when `errors` is non-empty.
138
+ - `RudiTabs` — Root of the tabs compound.
139
+ - `RudiTabList` — Container for the `RudiTab`s inside `RudiTabs`.
140
+ - `RudiTab` — A single tab in a `RudiTabList`.
141
+ - `RudiTabPanel` — Content shown when its tab is selected.
142
+ - `RudiEmptyState` — Placeholder for a view, table, or card with no content, explaining why and offering a next step.
143
+ - `RudiComboBox` — A searchable select: a text input that filters a list of options by case- and accent-insensitive substring match.
144
+ - `RudiToastRegion` — Renders toasts queued with `rudiToast`.
145
+ - `RudiTable` — Accessible data table built on React Aria Components' `Table`.
146
+ - `RudiTableHeader` — The header row.
147
+ - `RudiTableColumn` — A column header in `RudiTableHeader`.
148
+ - `RudiTableBody` — The table body.
149
+ - `RudiTableRow` — A table row.
150
+ - `RudiTableCell` — A data cell in a `RudiTableRow`, in the same order as the table's columns.
151
+ - `RudiDatePicker` — A date (or date and time) field with segmented keyboard entry and a calendar popover.
152
+ - `RudiDateRangePicker` — A start and end date field with segmented keyboard entry and a range calendar popover.
153
+ - `RudiNumberField` — A numeric field with locale-aware parsing, optional currency or percent formatting, and stepper buttons.
154
+
155
+ ## Components
156
+
157
+ ### RudiButton
158
+
159
+ A text button built on React Aria's `useButton`. Use it for actions on the page (save, delete, open a dialog); use a link for navigation. Handle activation with `onPress`, not `onClick`. For an icon-only button use `RudiIconButton`.
160
+
161
+ ```tsx
162
+ <RudiButton variant="primary" iconBefore="mdi:plus" onPress={addItem}>
163
+ Add item
164
+ </RudiButton>
165
+ ```
166
+
167
+ | Prop | Type | Default | Description |
168
+ | --- | --- | --- | --- |
169
+ | `children` *(required)* | `React.ReactNode` | | Button label, rendered in a `span`. It is the accessible name unless `aria-label` is set. |
170
+ | `variant` | `'primary' \| 'secondary' \| 'destructive' \| 'ghost'` | `'primary'` | Visual emphasis: `primary` for the main action, `destructive` for irreversible actions, `ghost` for low-emphasis ones. |
171
+ | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Button height and text size. |
172
+ | `isLoading` | `boolean` | `false` | Replaces the icons with a spinner, sets `aria-busy`, and disables the button so it cannot be pressed again. |
173
+ | `iconBefore` | `string` | | Iconify name shown before the label, e.g. `"mdi:plus"`. Not rendered while `isLoading`. |
174
+ | `iconAfter` | `string` | | Iconify name shown after the label, e.g. `"mdi:arrow-right"`. Not rendered while `isLoading`. |
175
+ | `className` | `string` | | Extra class names, merged with the component's own classes. |
176
+
177
+ Inherited from React Aria (types and descriptions in `components.json`): `isDisabled`, `onPress`, `onPressStart`, `onPressEnd`, `onPressChange`, `onPressUp`, `onClick`, `autoFocus`, `onFocus`, `onBlur`, `onFocusChange`, `onKeyDown`, `onKeyUp`, `href`, `target`, `rel`, `elementType`, `aria-disabled`, `aria-expanded`, `aria-haspopup`, `aria-controls`, `aria-pressed`, `aria-current`, `type`, `preventFocusOnPress`, `form`, `formAction`, `formEncType`, `formMethod`, `formNoValidate`, `formTarget`, `name`, `value`, `excludeFromTabOrder`, `id`, `aria-label`, `aria-labelledby`, `aria-describedby`, `aria-details`.
178
+
179
+ `ref` forwards to `HTMLButtonElement`.
180
+
181
+ ### RudiInput
182
+
183
+ A single-line text field with label, description and error message. `label` is required and is the accessible name. `onChange` receives the string value, not an event. The ref points at the `<input>`.
184
+
185
+ ```tsx
186
+ <RudiInput label="Email" type="email" value={email} onChange={setEmail} />
187
+ ```
188
+
189
+ | Prop | Type | Default | Description |
190
+ | --- | --- | --- | --- |
191
+ | `label` *(required)* | `string` | | Visible label and the field's accessible name. Required. |
192
+ | `type` | `'text' \| 'email' \| 'password' \| 'url' \| 'tel' \| 'search' \| 'number'` | `'text'` | Native input type. Prefer `RudiNumberField` over `"number"` for numeric entry. |
193
+ | `placeholder` | `string` | | Hint text shown while the field is empty. Not a substitute for `label`. |
194
+ | `description` | `string` | | Help text under the field. Hidden while `errorMessage` is shown. |
195
+ | `errorMessage` | `string` | | Error text shown under the field. Setting it marks the field invalid; leave it unset when the value is valid. |
196
+ | `isRequired` | `boolean` | `false` | Marks the field required and adds an asterisk to the label. |
197
+ | `isDisabled` | `boolean` | `false` | Disables the field. |
198
+ | `value` | `string` | | Controlled value. Pair with `onChange`. |
199
+ | `defaultValue` | `string` | | Initial value for an uncontrolled field. |
200
+ | `onChange` | `(value: string) => void` | | Called with the new text (a string, not an event) on every edit. |
201
+ | `onBlur` | `(event: React.FocusEvent<HTMLInputElement>) => void` | | Called when the field loses focus, e.g. to validate on blur. |
202
+ | `name` | `string` | | Form field name, for native form submission and password managers. |
203
+ | `autoComplete` | `string` | | Autofill hint, e.g. `email`, `one-time-code`, `current-password`. |
204
+ | `inputMode` | `'none' \| 'text' \| 'tel' \| 'url' \| 'email' \| 'numeric' \| 'decimal' \| 'search'` | | Virtual-keyboard hint, e.g. `numeric` for a one-time code. |
205
+ | `maxLength` | `number` | | Maximum number of characters the user can enter. |
206
+ | `isReadOnly` | `boolean` | | Makes the value selectable and focusable but not editable. |
207
+ | `autoFocus` | `boolean` | | Focuses the field on mount. |
208
+ | `className` | `string` | | Extra class names for the wrapper element, merged with the component's own classes. |
209
+
210
+ `ref` forwards to `HTMLInputElement`.
211
+
212
+ ### RudiCheckbox
213
+
214
+ A checkbox with a visible label. Inside a `RudiCheckboxGroup` it reads and updates the group's value
215
+ array (give it a `value`); on its own it is controlled with `isSelected` / `onChange`. The ref points at the `<input>`.
216
+
217
+ ```tsx
218
+ <RudiCheckbox isSelected={agreed} onChange={setAgreed}>I agree to the terms</RudiCheckbox>
219
+ ```
220
+
221
+ | Prop | Type | Default | Description |
222
+ | --- | --- | --- | --- |
223
+ | `children` *(required)* | `React.ReactNode` | | Visible label, rendered next to the box. |
224
+ | `isSelected` | `boolean` | | Controlled checked state for a standalone checkbox. Pair with `onChange`. Ignored inside a `RudiCheckboxGroup`. |
225
+ | `defaultSelected` | `boolean` | | Initial checked state for an uncontrolled standalone checkbox. |
226
+ | `isIndeterminate` | `boolean` | | Shows the mixed state (e.g. a "select all" box when only some children are checked). Sets the native `indeterminate` property so assistive tech announces "mixed", and shows the dash. It does not change `isSelected`. |
227
+ | `onChange` | `(isSelected: boolean) => void` | | Called with the new checked state (a boolean, not an event) for a standalone checkbox. |
228
+ | `isDisabled` | `boolean` | | Disables the checkbox. |
229
+ | `value` | `string` | | Required inside a RudiCheckboxGroup: the value added to the group's array when checked. On a standalone checkbox it is the value submitted under `name` in a native form. |
230
+ | `name` | `string` | | Form field name for a standalone checkbox. When checked, `name`=`value` is included in native form submission. |
231
+ | `errorMessage` | `string` | | Error shown under a standalone checkbox (e.g. an unaccepted agreement); marks it invalid. |
232
+ | `className` | `string` | | Extra class names, merged with the component's own classes. Always applied to the outermost element: the label, or the wrapper when `errorMessage` is set. |
233
+
234
+ `ref` forwards to `HTMLInputElement`.
235
+
236
+ ### RudiCheckboxGroup
237
+
238
+ A labelled set of `RudiCheckbox` options whose selection is a string array. `label` is required. Each child
239
+ checkbox must have a `value`.
240
+
241
+ ```tsx
242
+ <RudiCheckboxGroup label="Toppings" value={toppings} onChange={setToppings}>
243
+ <RudiCheckbox value="cheese">Cheese</RudiCheckbox>
244
+ <RudiCheckbox value="olives">Olives</RudiCheckbox>
245
+ </RudiCheckboxGroup>
246
+ ```
247
+
248
+ | Prop | Type | Default | Description |
249
+ | --- | --- | --- | --- |
250
+ | `label` *(required)* | `string` | | Group legend and accessible name. Required. |
251
+ | `children` *(required)* | `React.ReactNode` | | The `RudiCheckbox` elements. Each needs a `value`. |
252
+ | `description` | `string` | | Help text under the group. Hidden while `errorMessage` is shown. |
253
+ | `value` | `string[]` | | Controlled array of checked `RudiCheckbox` values. Pair with `onChange`. |
254
+ | `defaultValue` | `string[]` | | Initial checked values for an uncontrolled group. |
255
+ | `onChange` | `(value: string[]) => void` | | Called with the full array of checked values (not an event) whenever one changes. |
256
+ | `isDisabled` | `boolean` | | Disables every checkbox in the group. |
257
+ | `errorMessage` | `string` | | Error text shown under the group. Setting it marks the group invalid. |
258
+ | `className` | `string` | | Extra class names for the group element, merged with the component's own classes. |
259
+
260
+ ### RudiSelect
261
+
262
+ A dropdown for choosing one option from a list. Pass data via `items` and render each entry with a
263
+ `RudiOption` in `children`. `label` is required. Use `RudiComboBox` when the list is long enough to need search.
264
+
265
+ ```tsx
266
+ <RudiSelect label="Country" items={countries} onSelectionChange={setCountry}>
267
+ {(c) => <RudiOption key={c.id}>{c.name}</RudiOption>}
268
+ </RudiSelect>
269
+ ```
270
+
271
+ | Prop | Type | Default | Description |
272
+ | --- | --- | --- | --- |
273
+ | `label` *(required)* | `string` | | Visible label and the field's accessible name. Required. |
274
+ | `items` *(required)* | `Iterable<T>` | | The options as data. Each item is rendered by the `children` function; give items an `id` or `key` for stable selection. |
275
+ | `children` *(required)* | `(item: T) => React.ReactNode` | | Render function returning a `RudiOption` for each item. |
276
+ | `selectedKey` | `Key \| null` | | Controlled selected option key. Pair with `onSelectionChange`. |
277
+ | `defaultSelectedKey` | `Key \| null` | | Initial selected key for an uncontrolled select. |
278
+ | `onSelectionChange` | `(key: Key \| null) => void` | | Called with the chosen option's key (not an event). |
279
+ | `placeholder` | `string` | `'Select an option'` | Text shown when nothing is selected. |
280
+ | `description` | `string` | | Help text under the field. Hidden while `errorMessage` is shown. |
281
+ | `errorMessage` | `string` | | Error text shown under the field. Setting it marks the field invalid. |
282
+ | `name` | `string` | | Form field name. The selected option's key is submitted under this name in a native form. |
283
+ | `isRequired` | `boolean` | | Marks the field required for assistive tech and adds an asterisk to the label. It does not block native form submission. |
284
+ | `isDisabled` | `boolean` | | Disables the field. |
285
+ | `className` | `string` | | Extra class names for the wrapper element, merged with the component's own classes. |
286
+
287
+ ### RudiOption
288
+
289
+ Re-exported unchanged from `@react-stately/collections`.
290
+
291
+ One entry in a `RudiSelect` or `RudiComboBox` list. Its children are the visible content; set `textValue`
292
+ when the children are not plain text (used for typeahead and filtering). Give it a `key` (or `id`).
293
+
294
+ ```tsx
295
+ <RudiOption key="us">United States</RudiOption>
296
+ ```
297
+
298
+ Inherited from React Aria (types and descriptions in `components.json`): `children`, `title`, `textValue`, `aria-label`, `childItems`, `hasChildItems`, `href`, `hrefLang`, `target`, `rel`, `download`, `ping`, `referrerPolicy`, `routerOptions`.
299
+
300
+ ### RudiMenuTrigger
301
+
302
+ Connects a pressable trigger to a `RudiMenu`. It takes exactly two children: the trigger
303
+ element first (a `RudiButton` or `RudiIconButton`, which handle `onPress`), then the `RudiMenu`.
304
+ Open state is uncontrolled unless you pass `isOpen` and `onOpenChange`.
305
+
306
+ ```tsx
307
+ <RudiMenuTrigger>
308
+ <RudiButton variant="secondary">Actions</RudiButton>
309
+ <RudiMenu onAction={(key) => console.log(key)}>
310
+ <RudiMenuItem id="edit" label="Edit" />
311
+ <RudiMenuSeparator />
312
+ <RudiMenuItem id="delete" label="Delete" isDestructive />
313
+ </RudiMenu>
314
+ </RudiMenuTrigger>
315
+ ```
316
+
317
+ Inherited from React Aria (types and descriptions in `components.json`): `children`, `trigger`, `isOpen`, `defaultOpen`, `onOpenChange`.
318
+
319
+ ### RudiMenu
320
+
321
+ The popover and item list of a menu. Place it inside `RudiMenuTrigger`, after the trigger
322
+ element, and fill it with `RudiMenuItem`, `RudiMenuSection` and `RudiMenuSeparator`. It renders
323
+ its own popover, so do not wrap it in one. Handle activation with `onAction` (receives the item
324
+ key), or use `selectionMode` and `onSelectionChange` for checkable items.
325
+
326
+ ```tsx
327
+ <RudiMenu onAction={(key) => console.log(key)}>
328
+ <RudiMenuItem id="edit" label="Edit" />
329
+ </RudiMenu>
330
+ ```
331
+
332
+ | Prop | Type | Default | Description |
333
+ | --- | --- | --- | --- |
334
+ | `className` | `string` | `'react-aria-Menu'` | Class merged onto the menu list element, not the popover. |
335
+
336
+ Inherited from React Aria (types and descriptions in `components.json`): `renderEmptyState`, `shouldCloseOnSelect`, `autoFocus`, `id`, `aria-label`, `aria-labelledby`, `aria-describedby`, `aria-details`, `escapeKeyBehavior`, `shouldFocusWrap`, `onAction`, `onClose`, `items`, `disabledKeys`, `selectionMode`, `disallowEmptySelection`, `selectedKeys`, `defaultSelectedKeys`, `onSelectionChange`, `children`, `dependencies`, `style`.
337
+
338
+ Also accepts React Aria's global DOM props (`DOMRenderProps`, `GlobalDOMAttributes`, `GlobalDOMEvents`, `SlotProps`).
339
+
340
+ ### RudiMenuItem
341
+
342
+ A single action in a `RudiMenu`. Give it a `label` (plus optional `icon`, `description` and
343
+ `shortcut`) for structured content, or pass plain `children`. Give every item an `id`, which is
344
+ the key delivered to the menu's `onAction`. When `children` is not a plain string and no `label`
345
+ is set, pass `textValue` so typeahead works.
346
+
347
+ ```tsx
348
+ <RudiMenuItem id="delete" label="Delete" icon="mdi:delete" shortcut="⌫" isDestructive />
349
+ ```
350
+
351
+ | Prop | Type | Default | Description |
352
+ | --- | --- | --- | --- |
353
+ | `isDestructive` | `boolean` | | Styles the item as a destructive action (for example Delete) and sets `data-destructive`. |
354
+ | `icon` | `string` | | Iconify icon name rendered before the label. |
355
+ | `label` | `string` | | Primary text. When set, content is composed for you (no need to pass children). |
356
+ | `description` | `ReactNode` | | Secondary text shown beneath the label. |
357
+ | `shortcut` | `ReactNode` | | Keyboard shortcut hint shown at the trailing edge. |
358
+
359
+ Inherited from React Aria (types and descriptions in `components.json`): `className`, `id`, `value`, `textValue`, `aria-label`, `isDisabled`, `onAction`, `shouldCloseOnSelect`, `children`, `style`, `href`, `hrefLang`, `target`, `rel`, `download`, `ping`, `referrerPolicy`, `routerOptions`, `onHoverStart`, `onHoverEnd`, `onHoverChange`, `onFocus`, `onBlur`, `onFocusChange`, `onPress`, `onPressStart`, `onPressEnd`, `onPressChange`, `onPressUp`, `onClick`.
360
+
361
+ Also accepts React Aria's global DOM props (`GlobalDOMAttributes`, `GlobalDOMEvents`, `PossibleLinkDOMRenderProps`).
362
+
363
+ ### RudiMenuSection
364
+
365
+ Groups related `RudiMenuItem`s inside a `RudiMenu`, with an optional `title` heading. Use
366
+ `RudiMenuSeparator` instead when you only need a divider with no heading.
367
+
368
+ ```tsx
369
+ <RudiMenuSection title="Danger zone">
370
+ <RudiMenuItem id="delete" label="Delete" isDestructive />
371
+ </RudiMenuSection>
372
+ ```
373
+
374
+ | Prop | Type | Default | Description |
375
+ | --- | --- | --- | --- |
376
+ | `title` | `string` | | Heading rendered above the section's items. Omit for an unlabelled group. |
377
+ | `className` | `string` | `'react-aria-MenuSection'` | Class merged onto the section element. |
378
+
379
+ Inherited from React Aria (types and descriptions in `components.json`): `shouldCloseOnSelect`, `id`, `value`, `children`, `dependencies`, `aria-label`, `items`, `style`, `selectionMode`, `disallowEmptySelection`, `selectedKeys`, `defaultSelectedKeys`, `onSelectionChange`, `disabledKeys`.
380
+
381
+ Also accepts React Aria's global DOM props (`DOMRenderProps`, `GlobalDOMAttributes`, `GlobalDOMEvents`).
382
+
383
+ ### RudiMenuSeparator
384
+
385
+ Horizontal divider between groups of items in a `RudiMenu`. Use `RudiMenuSection` when the
386
+ group also needs a heading.
387
+
388
+ ```tsx
389
+ <RudiMenuSeparator />
390
+ ```
391
+
392
+ Inherited from React Aria (types and descriptions in `components.json`): `className`, `orientation`, `elementType`, `id`, `aria-label`, `aria-labelledby`, `aria-describedby`, `aria-details`, `style`.
393
+
394
+ Also accepts React Aria's global DOM props (`DOMRenderProps`, `GlobalDOMAttributes`, `GlobalDOMEvents`, `SlotProps`).
395
+
396
+ ### RudiKeyboard
397
+
398
+ Keyboard shortcut hint, styled as the trailing shortcut text of a menu item. `RudiMenuItem`
399
+ renders it for you through its `shortcut` prop. Use it directly only for custom item content.
400
+ The hint is visual only; it does not bind the shortcut.
401
+
402
+ ```tsx
403
+ <RudiKeyboard>⌘S</RudiKeyboard>
404
+ ```
405
+
406
+ | Prop | Type | Default | Description |
407
+ | --- | --- | --- | --- |
408
+ | `className` | `string` | | Extra class names, merged with the component's own classes. |
409
+ | `children` | `ReactNode` | | Content. |
410
+
411
+ `ref` forwards to `HTMLElement`. Also accepts React Aria's global DOM props (`DOMRenderProps`). Spreads remaining props onto the DOM element (`AriaAttributes`, `DOMAttributes`, `HTMLAttributes`).
412
+
413
+ ### RudiSubmenuTrigger
414
+
415
+ Nests a menu inside a `RudiMenu`. It takes two children: the `RudiMenuItem` that opens the
416
+ submenu, then a `RudiMenu` holding the nested items.
417
+
418
+ ```tsx
419
+ <RudiSubmenuTrigger>
420
+ <RudiMenuItem id="share" label="Share" />
421
+ <RudiMenu>
422
+ <RudiMenuItem id="email" label="Email" />
423
+ </RudiMenu>
424
+ </RudiSubmenuTrigger>
425
+ ```
426
+
427
+ Inherited from React Aria (types and descriptions in `components.json`): `children`, `delay`.
428
+
429
+ ### RudiSeparator
430
+
431
+ Re-exported unchanged from `react-aria-components`.
432
+
433
+ React Aria's `Separator`, re-exported unchanged and unstyled. Prefer
434
+ `RudiMenuSeparator` inside a `RudiMenu` and `RudiDivider` between page content.
435
+
436
+ ```tsx
437
+ <RudiSeparator />
438
+ ```
439
+
440
+ Inherited from React Aria (types and descriptions in `components.json`): `className`, `orientation`, `elementType`, `id`, `aria-label`, `aria-labelledby`, `aria-describedby`, `aria-details`, `style`.
441
+
442
+ `ref` forwards to `HTMLElement`. Also accepts React Aria's global DOM props (`DOMRenderProps`, `GlobalDOMAttributes`, `GlobalDOMEvents`, `SlotProps`).
443
+
444
+ ### RudiDialog
445
+
446
+ Modal dialog with a title, scrolling body and optional pinned footer. Use it for focused tasks
447
+ and confirmations that block the page; it traps focus, restores focus on close, and locks page
448
+ scroll. It is controlled: you own `isOpen` and must clear it in `onClose`. `title` is required
449
+ and is the accessible name. Put action buttons in `RudiDialog.Footer`, primary action last.
450
+ The forwarded ref points at the dialog panel element.
451
+
452
+ ```tsx
453
+ <RudiDialog isOpen={open} onClose={() => setOpen(false)} title="Delete shipment">
454
+ <p>This cannot be undone.</p>
455
+ <RudiDialog.Footer>
456
+ <RudiButton variant="secondary" onPress={() => setOpen(false)}>Cancel</RudiButton>
457
+ <RudiButton variant="destructive" onPress={handleDelete}>Delete</RudiButton>
458
+ </RudiDialog.Footer>
459
+ </RudiDialog>
460
+ ```
461
+
462
+ | Prop | Type | Default | Description |
463
+ | --- | --- | --- | --- |
464
+ | `isOpen` *(required)* | `boolean` | | Controls visibility. The dialog is controlled only; it renders nothing while `false`. |
465
+ | `onClose` *(required)* | `() => void` | | Called when the user dismisses the dialog (close button, Escape, or outside click). Set `isOpen` to `false` here. |
466
+ | `title` *(required)* | `string` | | Heading text. Rendered as the `h2` that gives the dialog its accessible name. |
467
+ | `children` *(required)* | `React.ReactNode` | | Dialog body. A `RudiDialog.Footer` child is pulled out and pinned below the scrolling body. |
468
+ | `isDismissable` | `boolean` | `true` | Allows closing with the header close button, Escape and outside click. When `false`, none of those close it and the close button is hidden, so provide an action in a `RudiDialog.Footer`. |
469
+ | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Panel width. |
470
+ | `closeLabel` | `string` | `'Close'` | Accessible label of the header close button. |
471
+ | `className` | `string` | | Class merged onto the dialog panel. |
472
+
473
+ `ref` forwards to `HTMLDivElement`.
474
+
475
+ #### RudiDialog.Footer
476
+
477
+ Action row pinned to the bottom of the dialog; primary action last.
478
+
479
+ | Prop | Type | Default | Description |
480
+ | --- | --- | --- | --- |
481
+ | `children` *(required)* | `React.ReactNode` | | Action buttons, primary action last. |
482
+ | `className` | `string` | | Class merged onto the footer element. |
483
+
484
+ ### RudiSwitch
485
+
486
+ An on/off toggle for settings that take effect immediately; use `RudiCheckbox` for choices submitted with a form. Needs a visible label (children) or `aria-label` / `aria-labelledby`. The ref points at the `<input>`.
487
+
488
+ ```tsx
489
+ <RudiSwitch isSelected={enabled} onChange={setEnabled}>Email notifications</RudiSwitch>
490
+ ```
491
+
492
+ | Prop | Type | Default | Description |
493
+ | --- | --- | --- | --- |
494
+ | `children` | `React.ReactNode` | | Visible label. Omit only when `aria-label` or `aria-labelledby` names the switch. |
495
+ | `aria-label` | `string` | | Accessible name, for switches whose visible text repeats (e.g. one per table row). |
496
+ | `aria-labelledby` | `string` | | Id of an element that names the switch, as an alternative to `aria-label`. |
497
+ | `isSelected` | `boolean` | | Controlled on/off state. Pair with `onChange`. |
498
+ | `defaultSelected` | `boolean` | | Initial on/off state for an uncontrolled switch. |
499
+ | `onChange` | `(isSelected: boolean) => void` | | Called with the new on/off state (a boolean, not an event). |
500
+ | `isDisabled` | `boolean` | | Disables the switch. |
501
+ | `className` | `string` | | Extra class names for the wrapper label, merged with the component's own classes. |
502
+
503
+ `ref` forwards to `HTMLInputElement`.
504
+
505
+ ### RudiRadioGroup
506
+
507
+ A labelled set of mutually exclusive `RudiRadio` options. `label` is required. The value is the selected
508
+ option's `value` string.
509
+
510
+ ```tsx
511
+ <RudiRadioGroup label="Billing" value={plan} onChange={setPlan}>
512
+ <RudiRadio value="monthly">Monthly</RudiRadio>
513
+ <RudiRadio value="yearly">Yearly</RudiRadio>
514
+ </RudiRadioGroup>
515
+ ```
516
+
517
+ | Prop | Type | Default | Description |
518
+ | --- | --- | --- | --- |
519
+ | `label` *(required)* | `string` | | Group legend and accessible name. Required. |
520
+ | `children` *(required)* | `React.ReactNode` | | The `RudiRadio` elements. |
521
+ | `description` | `string` | | Help text under the group. Hidden while `errorMessage` is shown. |
522
+ | `value` | `string` | | Controlled value of the selected `RudiRadio`. Pair with `onChange`. |
523
+ | `defaultValue` | `string` | | Initial selected value for an uncontrolled group. |
524
+ | `onChange` | `(value: string) => void` | | Called with the selected option's `value` (a string, not an event). |
525
+ | `orientation` | `'horizontal' \| 'vertical'` | | Lays the options out in a row or a column. Also sets arrow-key behaviour for assistive tech. Unset renders vertically. |
526
+ | `isDisabled` | `boolean` | | Disables every option in the group. |
527
+ | `errorMessage` | `string` | | Error text shown under the group. Setting it marks the group invalid. |
528
+ | `className` | `string` | | Extra class names for the group element, merged with the component's own classes. |
529
+
530
+ ### RudiRadio
531
+
532
+ A single option inside `RudiRadioGroup`. Must be rendered as a descendant of
533
+ a `RudiRadioGroup`, which owns the selection state. The ref points at the `<input>`.
534
+
535
+ ```tsx
536
+ <RudiRadio value="monthly">Monthly</RudiRadio>
537
+ ```
538
+
539
+ | Prop | Type | Default | Description |
540
+ | --- | --- | --- | --- |
541
+ | `value` *(required)* | `string` | | The value submitted and reported to the group's `onChange` when this option is selected. |
542
+ | `children` *(required)* | `React.ReactNode` | | Visible label for the option. |
543
+ | `isDisabled` | `boolean` | | Disables just this option. A disabled group disables every option. |
544
+ | `className` | `string` | | Extra class names, merged with the component's own classes. |
545
+
546
+ `ref` forwards to `HTMLInputElement`.
547
+
548
+ ### RudiTooltipTrigger
549
+
550
+ Shows a `RudiTooltip` when its trigger is hovered or focused. Takes exactly two children, the
551
+ trigger element then the `RudiTooltip`. The trigger is linked to the tooltip with
552
+ `aria-describedby`, so keep the tooltip to short supplementary text, not essential content or
553
+ interactive controls. The forwarded ref points at the wrapping `span`.
554
+
555
+ ```tsx
556
+ <RudiTooltipTrigger delay={300}>
557
+ <RudiIconButton aria-label="Refresh" onPress={refresh}><RudiIcon icon="mdi:refresh" /></RudiIconButton>
558
+ <RudiTooltip>Refresh data</RudiTooltip>
559
+ </RudiTooltipTrigger>
560
+ ```
561
+
562
+ | Prop | Type | Default | Description |
563
+ | --- | --- | --- | --- |
564
+ | `children` *(required)* | `[React.ReactElement, React.ReactElement]` | | Exactly two elements: the trigger (must accept a `ref`, e.g. `RudiButton`), then the `RudiTooltip`. |
565
+ | `delay` | `number` | `500` | Milliseconds the pointer or focus must rest on the trigger before the tooltip opens. |
566
+ | `closeDelay` | `number` | `0` | Milliseconds to wait before closing after the pointer or focus leaves. |
567
+
568
+ `ref` forwards to `HTMLSpanElement`.
569
+
570
+ ### RudiTooltip
571
+
572
+ Tooltip bubble. Use only as the second child of `RudiTooltipTrigger`, which controls when it
573
+ appears and where the open state comes from.
574
+
575
+ ```tsx
576
+ <RudiTooltip>Copy to clipboard</RudiTooltip>
577
+ ```
578
+
579
+ | Prop | Type | Default | Description |
580
+ | --- | --- | --- | --- |
581
+ | `children` *(required)* | `React.ReactNode` | | Tooltip text. |
582
+ | `className` | `string` | | Class merged onto the tooltip element. |
583
+
584
+ Inherited from React Aria (types and descriptions in `components.json`): `isOpen`, `id`, `aria-label`, `aria-labelledby`, `aria-describedby`, `aria-details`.
585
+
586
+ `ref` forwards to `HTMLSpanElement`.
587
+
588
+ ### RudiAlert
589
+
590
+ Inline message banner for status, feedback, or warnings that sit within the page content. Use `RudiTag` or `RudiBadge` for short labels, and a dialog for messages that must interrupt the user.
591
+ Renders `role="alert"` by default, which announces assertively; set `isPolite` for non-urgent updates. Dismissal is internal: once dismissed the alert unmounts and stays hidden until the component remounts.
592
+
593
+ ```tsx
594
+ <RudiAlert variant="warning" title="Storage almost full" dismissible>
595
+ You have used 92% of your quota.
596
+ </RudiAlert>
597
+ ```
598
+
599
+ | Prop | Type | Default | Description |
600
+ | --- | --- | --- | --- |
601
+ | `variant` *(required)* | `'info' \| 'success' \| 'warning' \| 'error'` | | Sets the semantic color and meaning of the alert. |
602
+ | `children` *(required)* | `React.ReactNode` | | Message body. |
603
+ | `title` | `string` | | Bold heading shown above the content. |
604
+ | `icon` | `string` | | Iconify icon name shown at the inline-start, e.g. `"mdi:alert"`. Decorative and hidden from assistive technology. |
605
+ | `isPolite` | `boolean` | `false` | Uses `role="status"` (polite announcement) instead of `role="alert"` (assertive). |
606
+ | `dismissible` | `boolean` | `false` | Shows a close button labelled "Dismiss alert". The alert hides itself when it is pressed. |
607
+ | `onDismiss` | `() => void` | | Called after the user dismisses the alert. |
608
+ | `action` | `React.ReactNode` | | Content at the inline-end of the alert, e.g. a button. Wraps below the text when space is tight. |
609
+ | `className` | `string` | | Extra class names, merged with the component's own classes rather than replacing them. |
610
+
611
+ ### RudiIconButton
612
+
613
+ A button that shows only an icon. Requires `aria-label` since there is no visible text; use `RudiButton` with `iconBefore` when a text label fits. Handle activation with `onPress`, not `onClick`.
614
+
615
+ ```tsx
616
+ <RudiIconButton aria-label="Close" onPress={close}>
617
+ <RudiIcon icon="mdi:close" />
618
+ </RudiIconButton>
619
+ ```
620
+
621
+ | Prop | Type | Default | Description |
622
+ | --- | --- | --- | --- |
623
+ | `aria-label` *(required)* | `string` | | Accessible name. Required because the button has no visible text. |
624
+ | `children` *(required)* | `React.ReactElement` | | The icon element, e.g. `<RudiIcon icon="mdi:close" />`. Must be a single element. |
625
+ | `variant` | `'primary' \| 'secondary' \| 'destructive' \| 'ghost'` | `'secondary'` | Visual emphasis: `primary` for the main action, `destructive` for irreversible actions, `ghost` for low-emphasis ones. |
626
+ | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Button height and icon size. |
627
+ | `isLoading` | `boolean` | `false` | Sets `aria-busy` and disables the button so it cannot be pressed again. Unlike `RudiButton`, it shows no spinner. |
628
+ | `className` | `string` | | Extra class names, merged with the component's own classes. |
629
+
630
+ Inherited from React Aria (types and descriptions in `components.json`): `isDisabled`, `onPress`, `onPressStart`, `onPressEnd`, `onPressChange`, `onPressUp`, `onClick`, `autoFocus`, `onFocus`, `onBlur`, `onFocusChange`, `onKeyDown`, `onKeyUp`, `href`, `target`, `rel`, `elementType`, `aria-disabled`, `aria-expanded`, `aria-haspopup`, `aria-controls`, `aria-pressed`, `aria-current`, `type`, `preventFocusOnPress`, `form`, `formAction`, `formEncType`, `formMethod`, `formNoValidate`, `formTarget`, `name`, `value`, `excludeFromTabOrder`, `id`, `aria-labelledby`, `aria-describedby`, `aria-details`.
631
+
632
+ `ref` forwards to `HTMLButtonElement`.
633
+
634
+ ### RudiBadge
635
+
636
+ Small non-interactive label for status or counts. Use `RudiTag` when the label can be pressed or dismissed, and `RudiDot` for a bare indicator.
637
+ With `dot` set the badge renders as a dot and `children` become screen-reader-only text.
638
+
639
+ ```tsx
640
+ <RudiBadge variant="success">Active</RudiBadge>
641
+ ```
642
+
643
+ | Prop | Type | Default | Description |
644
+ | --- | --- | --- | --- |
645
+ | `variant` | `'default' \| 'success' \| 'warning' \| 'error' \| 'info'` | `'default'` | Semantic color of the badge. |
646
+ | `size` | `'sm' \| 'md'` | `'md'` | Controls the badge's size. |
647
+ | `dot` | `boolean` | `false` | Renders a bare colored dot. `children` are kept as screen-reader-only text; with no children the dot is decorative. |
648
+ | `children` | `React.ReactNode` | | Badge content, such as a status word or count. With `dot` set it is visually hidden but still announced. |
649
+ | `className` | `string` | | Extra class names, merged with the component's own classes rather than replacing them. |
650
+
651
+ ### RudiTag
652
+
653
+ Compact label for a keyword, filter, or selection. Becomes a button when `onPress` is set (the tag stays a non-interactive wrapper around two sibling buttons), and shows a remove control when `dismissible`. Use `RudiBadge` for status that is never interactive.
654
+ Dismissal is internal: the tag unmounts after the remove control is pressed. The remove button is labelled "Remove {children}" when `children` is a string, otherwise "Remove".
655
+
656
+ ```tsx
657
+ <RudiTag variant="info" dismissible onDismiss={() => removeFilter('open')}>
658
+ Open
659
+ </RudiTag>
660
+ ```
661
+
662
+ | Prop | Type | Default | Description |
663
+ | --- | --- | --- | --- |
664
+ | `children` *(required)* | `React.ReactNode` | | Tag content, usually a short string. |
665
+ | `variant` | `'default' \| 'success' \| 'warning' \| 'error' \| 'info'` | `'default'` | Semantic color of the tag. |
666
+ | `dismissible` | `boolean` | `false` | Shows a remove control that hides the tag when pressed. |
667
+ | `onDismiss` | `() => void` | | Called after the user removes the tag. Not called when `isDisabled` is set. |
668
+ | `onPress` | `() => void` | | Makes the tag's content a button; called when it is pressed. Without it the tag is static text. The remove control stays a separate sibling button. |
669
+ | `isDisabled` | `boolean` | `false` | Disables the tag's press behavior and its remove control, and marks it `aria-disabled`. |
670
+ | `className` | `string` | | Extra class names, merged with the component's own classes rather than replacing them. |
671
+
672
+ ### RudiIcon
673
+
674
+ Renders an Iconify icon by name (for example `"mdi:close"`). Icons are always passed as name strings, never imported components.
675
+ Decorative by default (`aria-hidden`). Pass `label` to expose it as an image with an accessible name. Forwards its ref to the wrapping `span`.
676
+
677
+ ```tsx
678
+ <RudiIcon icon="mdi:check-circle" size="lg" label="Verified" />
679
+ ```
680
+
681
+ | Prop | Type | Default | Description |
682
+ | --- | --- | --- | --- |
683
+ | `icon` *(required)* | `string` | | Iconify icon name in `prefix:name` form, e.g. `"mdi:close"` or `"lucide:check"`. |
684
+ | `size` | `'sm' \| 'md' \| 'lg' \| number` | `'md'` | Preset size, or a number for an exact width and height in px. |
685
+ | `color` | `string` | | CSS color applied to the icon. Defaults to the inherited text color (`currentColor`). |
686
+ | `label` | `string` | | Accessible name. When set the icon is exposed as `role="img"`; when omitted it is hidden from assistive technology. |
687
+ | `className` | `string` | | Extra class names, merged with the component's own classes rather than replacing them. |
688
+
689
+ `ref` forwards to `HTMLSpanElement`.
690
+
691
+ ### RudiCard
692
+
693
+ Surface container that groups related content. Compose it with `RudiCard.Header`, `RudiCard.Body`, and `RudiCard.Footer`. Use `RudiStatCard` for a single metric.
694
+ Forwards its ref to the root `div`.
695
+
696
+ ```tsx
697
+ <RudiCard variant="outlined">
698
+ <RudiCard.Header>Billing</RudiCard.Header>
699
+ <RudiCard.Body>Next invoice on 1 March.</RudiCard.Body>
700
+ </RudiCard>
701
+ ```
702
+
703
+ | Prop | Type | Default | Description |
704
+ | --- | --- | --- | --- |
705
+ | `children` *(required)* | `React.ReactNode` | | Card content, usually `RudiCard.Header`, `RudiCard.Body`, and `RudiCard.Footer`. |
706
+ | `variant` | `'default' \| 'outlined' \| 'elevated'` | `'default'` | Surface treatment: plain, bordered, or raised with a shadow. |
707
+ | `padding` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Inner padding of the card. |
708
+ | `className` | `string` | | Extra class names, merged with the component's own classes rather than replacing them. |
709
+
710
+ `ref` forwards to `HTMLDivElement`.
711
+
712
+ #### RudiCard.Header
713
+
714
+ Top section of the card; holds the title and actions.
715
+
716
+ | Prop | Type | Default | Description |
717
+ | --- | --- | --- | --- |
718
+ | `children` *(required)* | `React.ReactNode` | | Header content, such as a title and actions. |
719
+ | `className` | `string` | | Extra class names, merged with the component's own classes rather than replacing them. |
720
+
721
+ #### RudiCard.Body
722
+
723
+ Main content area of the card.
724
+
725
+ | Prop | Type | Default | Description |
726
+ | --- | --- | --- | --- |
727
+ | `children` *(required)* | `React.ReactNode` | | Main card content. |
728
+ | `className` | `string` | | Extra class names, merged with the component's own classes rather than replacing them. |
729
+
730
+ #### RudiCard.Footer
731
+
732
+ Bottom section of the card; holds buttons or metadata.
733
+
734
+ | Prop | Type | Default | Description |
735
+ | --- | --- | --- | --- |
736
+ | `children` *(required)* | `React.ReactNode` | | Footer content, such as buttons or metadata. |
737
+ | `className` | `string` | | Extra class names, merged with the component's own classes rather than replacing them. |
738
+
739
+ ### RudiProgressBar
740
+
741
+ Horizontal bar showing determinate progress. Use `RudiCircularProgress` for a compact circular form.
742
+ `label` is required and is the accessible name; it is also shown above the bar. The fill is clamped to 0 to 100%.
743
+
744
+ ```tsx
745
+ <RudiProgressBar label="Storage used" value={72} showValueLabel thresholds={[{ at: 90, variant: 'error' }]} />
746
+ ```
747
+
748
+ | Prop | Type | Default | Description |
749
+ | --- | --- | --- | --- |
750
+ | `value` *(required)* | `number` | | Current progress, between `minValue` and `maxValue`. |
751
+ | `label` *(required)* | `string` | | Accessible name, also displayed above the bar. |
752
+ | `minValue` | `number` | `0` | Value that represents 0%. |
753
+ | `maxValue` | `number` | `100` | Value that represents 100%. |
754
+ | `showValueLabel` | `boolean` | `false` | Shows the rounded percentage beside the label. |
755
+ | `variant` | `RudiProgressBarVariant` | `'default'` | Fill color when no threshold applies. |
756
+ | `thresholds` | `RudiProgressBarThreshold[]` | | Percentage-driven fill color. The highest `at` the current percentage meets or exceeds wins; below every threshold the `variant` prop applies. e.g. `[{ at: 80, variant: 'warning' }, { at: 100, variant: 'error' }]`. |
757
+ | `size` | `'sm' \| 'md'` | `'md'` | Thickness of the track. |
758
+ | `className` | `string` | | Extra class names, merged with the component's own classes rather than replacing them. |
759
+
760
+ ### RudiDivider
761
+
762
+ Thin rule that separates sections of content. Renders a native `hr` for a plain horizontal rule, and a `role="separator"` element when vertical or labelled.
763
+ A `label` only applies to horizontal dividers; it is ignored when `orientation="vertical"`.
764
+
765
+ ```tsx
766
+ <RudiDivider label="or" />
767
+ ```
768
+
769
+ | Prop | Type | Default | Description |
770
+ | --- | --- | --- | --- |
771
+ | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Direction of the rule. |
772
+ | `spacing` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Margin around the rule, on the block axis when horizontal and the inline axis when vertical. |
773
+ | `label` | `ReactNode` | | Centered label rendered between two rules. Horizontal only; ignored when vertical. |
774
+ | `className` | `string` | | Extra class names, merged with the component's own classes rather than replacing them. |
775
+
776
+ ### RudiDot
777
+
778
+ Small colored circle for status or category. Use `RudiBadge` when the indicator needs text beside it.
779
+ Decorative (`aria-hidden`) unless `label` is set, in which case it is exposed as a status with visually hidden text.
780
+
781
+ ```tsx
782
+ <RudiDot tone="success" pulse label="Live" />
783
+ ```
784
+
785
+ | Prop | Type | Default | Description |
786
+ | --- | --- | --- | --- |
787
+ | `tone` | `'default' \| 'success' \| 'warning' \| 'error' \| 'info'` | `'default'` | Semantic color of the dot. Ignored when `color` is set. |
788
+ | `color` | `string` | | Explicit CSS color or token, e.g. `var(--rudi-color-dataviz-3)`, for domain accents. Overrides `tone`. |
789
+ | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Diameter of the dot. |
790
+ | `pulse` | `boolean` | `false` | Renders an animated halo to draw attention, e.g. for a "live" state. |
791
+ | `label` | `string` | | Accessible label. When set the dot is exposed as `role="status"` with visually hidden text; otherwise it is hidden from assistive technology. |
792
+ | `className` | `string` | | Extra class names, merged with the component's own classes rather than replacing them. |
793
+
794
+ ### RudiLink
795
+
796
+ Styled anchor for navigation. Use `RudiButton` for actions that do not navigate.
797
+ Same-tab clicks route client-side when a `RudiRouterProvider` is mounted, and behave as a plain link otherwise. With `external`, the link opens in a new tab with `rel="noreferrer noopener"` and shows an arrow icon. Forwards its ref to the `a`.
798
+
799
+ ```tsx
800
+ <RudiLink href="https://example.com/docs" external>
801
+ Read the docs
802
+ </RudiLink>
803
+ ```
804
+
805
+ | Prop | Type | Default | Description |
806
+ | --- | --- | --- | --- |
807
+ | `href` *(required)* | `string` | | Destination URL. |
808
+ | `children` *(required)* | `React.ReactNode` | | Link text or content. |
809
+ | `variant` | `'default' \| 'subtle' \| 'standalone'` | `'default'` | `default` inherits weight and uses the brand color; `subtle` is muted until hover; `standalone` is a self-contained link (e.g. "Learn more") in a heavier weight, laid out inline-flex so an icon child sits beside the text. |
810
+ | `underline` | `'always' \| 'hover' \| 'none'` | `'hover'` | When the underline is drawn. |
811
+ | `external` | `boolean` | `false` | Opens in a new tab with safe `rel` and appends an external-link icon. |
812
+ | `className` | `string` | | Extra class names, merged with the component's own classes rather than replacing them. |
813
+
814
+ `ref` forwards to `HTMLAnchorElement`. Spreads remaining props onto the DOM element (`AnchorHTMLAttributes`, `AriaAttributes`, `DOMAttributes`, `HTMLAttributes`).
815
+
816
+ ### RudiImage
817
+
818
+ Image in a framed, rounded container with an optional aspect ratio and overlay layer. Use it instead of a bare `img` when the image needs a fixed shape or content layered on top.
819
+ `alt` is required; pass an empty string for a purely decorative image. When the image fails to load, `fallback` (or a neutral placeholder) is shown in its place.
820
+
821
+ ```tsx
822
+ <RudiImage src="/shoe.jpg" alt="Red running shoe" aspectRatio="4 / 3" overlay={<RudiBadge>New</RudiBadge>} />
823
+ ```
824
+
825
+ | Prop | Type | Default | Description |
826
+ | --- | --- | --- | --- |
827
+ | `src` *(required)* | `string` | | Image URL. |
828
+ | `alt` *(required)* | `string` | | Text alternative for the image. Use an empty string when the image is decorative. |
829
+ | `aspectRatio` | `CSSProperties['aspectRatio']` | | CSS aspect ratio for the frame, e.g. `'16 / 9'`, `'1 / 1'`, `'4 / 3'`. Without it the frame sizes to the image. |
830
+ | `fit` | `'cover' \| 'contain'` | `'cover'` | How the image fills the frame: `cover` crops to fill, `contain` shows the whole image. |
831
+ | `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `'md'` | Corner radius of the frame. |
832
+ | `loading` | `'lazy' \| 'eager'` | `'lazy'` | Native loading strategy for the `img`. |
833
+ | `fallback` | `ReactNode` | | Content shown in place of the image when it fails to load. Defaults to a muted placeholder with an `image-off` icon that keeps the frame's `aspectRatio` and `radius`. |
834
+ | `onError` | `(event: SyntheticEvent<HTMLImageElement>) => void` | | Called when the image fails to load. |
835
+ | `overlay` | `ReactNode` | | Content layered over the image (badges, wishlist button, gradient scrim, duotone wash). Rendered in a positioned layer above the picture. |
836
+ | `className` | `string` | | Extra class names, merged with the component's own classes rather than replacing them. |
837
+
838
+ ### RudiRating
839
+
840
+ Star rating display that becomes an input when `onChange` is provided. Static mode is a single `role="img"`; interactive mode is a `radiogroup` of one native radio input per star, with a single tab stop and arrow-key navigation.
841
+ Controlled only: the parent owns `value`. In interactive mode `value` is rounded to a whole number for display and selection, so half stars appear only in static mode.
842
+
843
+ ```tsx
844
+ <RudiRating value={rating} onChange={setRating} label="Rate this product" />
845
+ ```
846
+
847
+ | Prop | Type | Default | Description |
848
+ | --- | --- | --- | --- |
849
+ | `value` *(required)* | `number` | | Current rating. Supports halves (e.g. `4.5`) in static mode. When `onChange` is set the value is rounded to the nearest whole number for display and selection, so half stars appear only in static mode. |
850
+ | `max` | `number` | `5` | Number of stars. |
851
+ | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size of the stars. |
852
+ | `onChange` | `(value: number) => void` | | Makes the rating interactive. Called with the new rating (1 to `max`) when a star is chosen by pointer or keyboard (Arrow keys move and select, Home and End jump to the first and last star); receives the value, not an event. |
853
+ | `showValue` | `boolean` | `false` | Shows the numeric value (e.g. `4.8`) beside the stars. |
854
+ | `count` | `number` | | Review count rendered beside the stars, e.g. `(128)`. |
855
+ | `label` | `string` | | Accessible name. Defaults to `"Rated {value} out of {max}"`. |
856
+ | `className` | `string` | | Extra class names, merged with the component's own classes rather than replacing them. |
857
+
858
+ ### RudiStepper
859
+
860
+ Ordered list of steps that shows progress through a multi-step process. Display only: it has no internal state or navigation, so set each step's `status` from your own state.
861
+ The step with `status: 'current'` gets `aria-current="step"`; steps without a status are treated as `upcoming`.
862
+
863
+ ```tsx
864
+ <RudiStepper
865
+ steps={[
866
+ { label: 'Cart', status: 'complete' },
867
+ { label: 'Payment', status: 'current' },
868
+ { label: 'Confirm' },
869
+ ]}
870
+ />
871
+ ```
872
+
873
+ | Prop | Type | Default | Description |
874
+ | --- | --- | --- | --- |
875
+ | `steps` *(required)* | `RudiStepperStep[]` | | Steps in order. |
876
+ | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | `horizontal` is a progress track; `vertical` is a timeline. |
877
+ | `size` | `'sm' \| 'md'` | `'md'` | Size of the step nodes and text. |
878
+ | `className` | `string` | | Extra class names, merged with the component's own classes rather than replacing them. |
879
+
880
+ ### RudiTextarea
881
+
882
+ A multi-line text field with label, description and error message. `label` is required and is the accessible name. `onChange` receives the string value, not an event. The ref points at the `<textarea>`.
883
+
884
+ ```tsx
885
+ <RudiTextarea label="Notes" rows={6} value={notes} onChange={setNotes} />
886
+ ```
887
+
888
+ | Prop | Type | Default | Description |
889
+ | --- | --- | --- | --- |
890
+ | `label` *(required)* | `string` | | Visible label and the field's accessible name. Required. |
891
+ | `placeholder` | `string` | | Hint text shown while the field is empty. Not a substitute for `label`. |
892
+ | `description` | `string` | | Help text under the field. Hidden while `errorMessage` is shown. |
893
+ | `errorMessage` | `string` | | Error text shown under the field. Setting it marks the field invalid; leave it unset when the value is valid. |
894
+ | `isRequired` | `boolean` | `false` | Marks the field required and adds an asterisk to the label. |
895
+ | `isDisabled` | `boolean` | `false` | Disables the field. |
896
+ | `value` | `string` | | Controlled value. Pair with `onChange`. |
897
+ | `defaultValue` | `string` | | Initial value for an uncontrolled field. |
898
+ | `onChange` | `(value: string) => void` | | Called with the new text (a string, not an event) on every edit. |
899
+ | `onBlur` | `(event: React.FocusEvent<HTMLTextAreaElement>) => void` | | Called when the field loses focus, e.g. to validate on blur. |
900
+ | `name` | `string` | | Form field name, for native form submission. |
901
+ | `maxLength` | `number` | | Maximum number of characters the user can enter. |
902
+ | `isReadOnly` | `boolean` | | Makes the value selectable and focusable but not editable. |
903
+ | `autoFocus` | `boolean` | | Focuses the field on mount. |
904
+ | `rows` | `number` | `4` | Visible height in text rows. |
905
+ | `resize` | `'none' \| 'vertical' \| 'horizontal' \| 'both'` | `'vertical'` | Which directions the user can drag-resize the field. |
906
+ | `className` | `string` | | Extra class names for the wrapper element, merged with the component's own classes. |
907
+
908
+ `ref` forwards to `HTMLTextAreaElement`.
909
+
910
+ ### RudiBreadcrumb
911
+
912
+ Navigation trail showing where the current page sits in a hierarchy. Items are ordered root first; the last item is always rendered as the current page (`aria-current="page"`) and is not a link, even if it has an `href`.
913
+ Links route client-side when a `RudiRouterProvider` is mounted.
914
+
915
+ ```tsx
916
+ <RudiBreadcrumb
917
+ items={[{ label: 'Home', href: '/' }, { label: 'Orders', href: '/orders' }, { label: 'Order 1042' }]}
918
+ />
919
+ ```
920
+
921
+ | Prop | Type | Default | Description |
922
+ | --- | --- | --- | --- |
923
+ | `items` *(required)* | `RudiBreadcrumbItem[]` | | Trail entries in order, from root to current page. |
924
+ | `separator` | `string` | `'lucide:chevron-right'` | Iconify name for the separator between items. |
925
+ | `label` | `string` | `'Breadcrumb'` | Accessible label for the nav landmark. |
926
+ | `className` | `string` | | Extra class names, merged with the component's own classes rather than replacing them. |
927
+
928
+ ### RudiPagination
929
+
930
+ Page navigation with previous and next buttons and numbered pages, truncated with ellipses for long ranges. Controlled: the parent owns `page`. A `page` outside 1 to `pageCount` is clamped for rendering.
931
+ Renders nothing when `pageCount` is 1 or less.
932
+
933
+ ```tsx
934
+ <RudiPagination page={page} pageCount={12} onPageChange={setPage} />
935
+ ```
936
+
937
+ | Prop | Type | Default | Description |
938
+ | --- | --- | --- | --- |
939
+ | `page` *(required)* | `number` | | Current page (1-based). |
940
+ | `pageCount` *(required)* | `number` | | Total number of pages. |
941
+ | `onPageChange` *(required)* | `(page: number) => void` | | Called with the new 1-based page number when the user picks a page. Not called when the target is the current page. |
942
+ | `siblingCount` | `number` | `1` | Pages shown on each side of the current page before truncating. |
943
+ | `label` | `string` | `'Pagination'` | Accessible label for the nav landmark. |
944
+ | `className` | `string` | | Extra class names, merged with the component's own classes rather than replacing them. |
945
+
946
+ ### RudiAvatar
947
+
948
+ Circular representation of a person or entity: an image when `src` loads, otherwise initials derived from `name`. Falls back to initials if the image fails to load.
949
+ Exposed as `role="img"` labelled by `alt`, then `name`. With neither, the avatar is decorative (`aria-hidden`, no role).
950
+
951
+ ```tsx
952
+ <RudiAvatar name="Ada Lovelace" src="/ada.jpg" size="lg" status="success" />
953
+ ```
954
+
955
+ | Prop | Type | Default | Description |
956
+ | --- | --- | --- | --- |
957
+ | `src` | `string` | | Image URL. When it is missing or fails to load, initials are shown instead. |
958
+ | `alt` | `string` | | Accessible name of the avatar. Takes precedence over `name` for the label. |
959
+ | `name` | `string` | | Full name used for the initials (first and last word, uppercased) and as the fallback accessible name. |
960
+ | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Diameter of the avatar. |
961
+ | `status` | `'success' \| 'warning' \| 'error' \| 'info'` | | Shows a small status dot in the corner. Without `statusLabel` the dot carries no text, so convey the status elsewhere for assistive technology. |
962
+ | `statusLabel` | `string` | | Text for the status, appended to the accessible name ("Ada Lovelace, Busy"). Only used when `status` is set. |
963
+ | `className` | `string` | | Extra class names, merged with the component's own classes rather than replacing them. |
964
+
965
+ ### RudiStatCard
966
+
967
+ Outlined card showing one headline metric with an optional change indicator. Built on `RudiCard`.
968
+ The trend is shown by color and an icon, and announced to screen readers (see `trendLabel`).
969
+
970
+ ```tsx
971
+ <RudiStatCard label="Revenue" value="$48,200" delta="+4.2%" trend="up" />
972
+ ```
973
+
974
+ | Prop | Type | Default | Description |
975
+ | --- | --- | --- | --- |
976
+ | `label` *(required)* | `string` | | Name of the metric, shown above the value. |
977
+ | `value` *(required)* | `string \| number` | | The headline figure. |
978
+ | `delta` | `string` | | Change text such as `"+4.2%"`, colored by `trend`. |
979
+ | `trend` | `'up' \| 'down' \| 'neutral'` | `'neutral'` | Direction of the change; sets the delta color and shows a trend icon next to it. |
980
+ | `trendLabel` | `string` | | Screen-reader text for the trend, read before `delta`. Defaults to "Increased", "Decreased" or "No change" by `trend`. |
981
+ | `children` | `React.ReactNode` | | Extra content below the value, such as a `RudiSparkline`. |
982
+ | `className` | `string` | | Extra class names, merged with the component's own classes rather than replacing them. |
983
+
984
+ ### RudiNavItem
985
+
986
+ Navigation entry for a sidebar: an `a` when `href` is set, otherwise a `button`. Use it inside `RudiAppShell.Sidebar`; it does not spread DOM props. The ref points to whichever element renders.
987
+
988
+ ```tsx
989
+ <RudiNavItem label="Projects" icon="mdi:folder" href="/projects" isActive />
990
+ ```
991
+
992
+ | Prop | Type | Default | Description |
993
+ | --- | --- | --- | --- |
994
+ | `label` *(required)* | `string` | | Visible text and accessible name of the item. |
995
+ | `icon` | `string` | | Iconify icon name shown before the label, such as `"mdi:home"`. |
996
+ | `isActive` | `boolean` | | Marks the item as the current location and applies the active style; sets `aria-current`. |
997
+ | `href` | `string` | | Renders the item as a link to this URL; without it the item is a button. Routes client-side under `RudiRouterProvider`. |
998
+ | `onPress` | `() => void` | | Called when the item is activated by pointer, keyboard, or touch. Use this, not `onClick`. |
999
+ | `badge` | `React.ReactNode` | | Content shown after the label, such as a count. |
1000
+ | `isDisabled` | `boolean` | | Prevents interaction and applies the disabled style. |
1001
+ | `className` | `string` | | Extra class names, merged with the built-in classes. |
1002
+
1003
+ `ref` forwards to `HTMLElement`.
1004
+
1005
+ ### RudiCircularProgress
1006
+
1007
+ Ring showing determinate progress, with optional content in the center. Use `RudiProgressBar` for a linear form.
1008
+ `label` is required; it is the accessible name and is also rendered as visible text below the ring.
1009
+
1010
+ ```tsx
1011
+ <RudiCircularProgress label="Profile complete" value={65} showValueLabel />
1012
+ ```
1013
+
1014
+ | Prop | Type | Default | Description |
1015
+ | --- | --- | --- | --- |
1016
+ | `value` *(required)* | `number` | | Current progress, between `minValue` and `maxValue`. Values outside that range are clamped, and the ring shows 0% when the range is empty. |
1017
+ | `label` *(required)* | `string` | | Accessible name of the progress indicator. |
1018
+ | `minValue` | `number` | `0` | Value that represents 0%. |
1019
+ | `maxValue` | `number` | `100` | Value that represents 100%. |
1020
+ | `showValueLabel` | `boolean` | `false` | Shows the rounded percentage in the center. Ignored when `children` is provided. |
1021
+ | `variant` | `'default' \| 'success' \| 'warning' \| 'error'` | `'default'` | Semantic color of the ring. |
1022
+ | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Diameter of the ring. |
1023
+ | `children` | `React.ReactNode` | | Custom content for the center of the ring; replaces the percentage text. |
1024
+ | `className` | `string` | | Extra class names, merged with the component's own classes rather than replacing them. |
1025
+
1026
+ ### RudiBarChart
1027
+
1028
+ Bar chart with one series per data key, built on Recharts and the library chart theme. Use `RudiLineChart` for trends over time.
1029
+ `label` is required; the chart is exposed as a single `role="img"` with that name, so summarize the data in it. It fills its container's width.
1030
+
1031
+ ```tsx
1032
+ <RudiBarChart
1033
+ label="Orders per month"
1034
+ data={[{ month: 'Jan', orders: 12 }, { month: 'Feb', orders: 18 }]}
1035
+ indexKey="month"
1036
+ dataKeys={['orders']}
1037
+ />
1038
+ ```
1039
+
1040
+ | Prop | Type | Default | Description |
1041
+ | --- | --- | --- | --- |
1042
+ | `data` *(required)* | `Array<Record<string, string \| number \| null>>` | | Row data. Values may be `null` to represent gaps in a series. Strongly-typed data objects are accepted directly, with no cast required. |
1043
+ | `dataKeys` *(required)* | `string[]` | | Keys of `data` rows to plot, one bar series each. Colors come from the chart theme in order. |
1044
+ | `indexKey` *(required)* | `string` | | Key of `data` rows used for the category axis labels. |
1045
+ | `label` *(required)* | `string` | | Accessible name describing the chart. |
1046
+ | `layout` | `'vertical' \| 'horizontal'` | `'vertical'` | `vertical` draws upright columns with categories along the x axis; `horizontal` draws sideways bars with categories along the y axis. |
1047
+ | `stacked` | `boolean` | `false` | Stacks the series instead of placing them side by side. |
1048
+ | `showLegend` | `boolean` | `true` | Shows the series legend. |
1049
+ | `showGrid` | `boolean` | `true` | Shows grid lines along the value axis. |
1050
+ | `height` | `number` | `300` | Chart height in px. |
1051
+ | `className` | `string` | | Extra class names, merged with the component's own classes rather than replacing them. |
1052
+
1053
+ ### RudiLineChart
1054
+
1055
+ Line chart with one series per data key, built on Recharts and the library chart theme. Use `RudiBarChart` to compare categories.
1056
+ `label` is required; the chart is exposed as a single `role="img"` with that name, so summarize the data in it. It fills its container's width.
1057
+
1058
+ ```tsx
1059
+ <RudiLineChart
1060
+ label="Temperature over 24 hours"
1061
+ data={readings}
1062
+ indexKey="time"
1063
+ dataKeys={['temp']}
1064
+ unit="°C"
1065
+ referenceLines={[{ y: 8, label: 'Set point', tone: 'warning' }]}
1066
+ />
1067
+ ```
1068
+
1069
+ | Prop | Type | Default | Description |
1070
+ | --- | --- | --- | --- |
1071
+ | `data` *(required)* | `Array<Record<string, string \| number \| null>>` | | Row data. Values may be `null` to represent gaps in a series (e.g. a burndown line that stops partway through the sprint). Strongly-typed data objects are accepted directly, with no cast required. |
1072
+ | `dataKeys` *(required)* | `string[]` | | Keys of `data` rows to plot, one line each. Colors come from the chart theme in order. |
1073
+ | `indexKey` *(required)* | `string` | | Key of `data` rows used for the x axis labels. |
1074
+ | `label` *(required)* | `string` | | Accessible name describing the chart. |
1075
+ | `curved` | `boolean` | `true` | Draws smoothed lines instead of straight segments. |
1076
+ | `showDots` | `boolean` | `true` | Draws a dot at each data point. |
1077
+ | `showGrid` | `boolean` | `true` | Shows grid lines. |
1078
+ | `showLegend` | `boolean` | `true` | Shows the series legend. |
1079
+ | `height` | `number` | `300` | Chart height in px. |
1080
+ | `referenceLines` | `RudiChartReferenceLine[]` | `[]` | Horizontal guide lines, e.g. a temperature set-point or a target. The y axis extends to keep them in view. |
1081
+ | `yDomain` | `[number \| 'auto', number \| 'auto']` | | Y-axis range; use `'auto'` for either end. Keeps reference lines in view. |
1082
+ | `unit` | `string` | | Unit suffix for y-axis ticks and tooltip values, e.g. `°C`. |
1083
+ | `className` | `string` | | Extra class names, merged with the component's own classes rather than replacing them. |
1084
+
1085
+ ### RudiSparkline
1086
+
1087
+ Tiny axis-less line for showing a trend inside a card, table cell, or sentence. Plain SVG with no Recharts dependency. Use `RudiLineChart` when the reader needs axes or tooltips.
1088
+ `label` is required and is the accessible name. Non-finite values in `data` are dropped. A single point is drawn as a dot.
1089
+
1090
+ ```tsx
1091
+ <RudiSparkline label="Temperature over the last 24 hours" data={[4, 5, 7, 6, 8]} tone="brand" showEndpoint />
1092
+ ```
1093
+
1094
+ | Prop | Type | Default | Description |
1095
+ | --- | --- | --- | --- |
1096
+ | `data` *(required)* | `number[]` | | Values in order, plotted left to right and scaled to fit the height. |
1097
+ | `label` *(required)* | `string` | | Accessible name, e.g. "Temperature over the last 24 hours". |
1098
+ | `width` | `number \| string` | | Fixed width in px, or any CSS length when a string. Defaults to filling the container. |
1099
+ | `height` | `number \| string` | | Fixed height in px, or any CSS length when a string. Defaults to the sparkline height token (2.5rem). |
1100
+ | `threshold` | `number` | | Draws a dashed horizontal reference line; the y domain always includes it. |
1101
+ | `tone` | `'neutral' \| 'brand' \| 'error' \| 'success'` | `'neutral'` | Semantic color of the line. |
1102
+ | `showEndpoint` | `boolean` | `false` | Draws a dot on the last point. |
1103
+ | `className` | `string` | | Extra class names, merged with the component's own classes rather than replacing them. |
1104
+
1105
+ ### RudiDonutChart
1106
+
1107
+ Donut chart showing parts of a whole, built on Recharts and the library chart theme. Slice colors come from the chart theme in order.
1108
+ `label` is required; the chart is exposed as a single `role="img"` with that name, so summarize the data in it.
1109
+
1110
+ ```tsx
1111
+ <RudiDonutChart label="Tickets by status" data={[{ name: 'Open', value: 14 }, { name: 'Closed', value: 52 }]} />
1112
+ ```
1113
+
1114
+ | Prop | Type | Default | Description |
1115
+ | --- | --- | --- | --- |
1116
+ | `data` *(required)* | `RudiDonutChartDatum[]` | | Slices to draw, in order. |
1117
+ | `label` *(required)* | `string` | | Accessible name describing the chart. |
1118
+ | `innerRadius` | `number` | `60` | Radius of the center hole in px. The ring is 30px thick. |
1119
+ | `showLabels` | `boolean` | `false` | Shows each slice's name beside it. |
1120
+ | `showLegend` | `boolean` | `true` | Shows the legend. |
1121
+ | `height` | `number` | `300` | Chart height in px. |
1122
+ | `className` | `string` | | Extra class names, merged with the component's own classes rather than replacing them. |
1123
+
1124
+ ### RudiKanbanBoard
1125
+
1126
+ Drag-and-drop board of columns and cards, with pointer and keyboard dragging and screen-reader
1127
+ announcements. Fully controlled: pass `columns`, and apply each `onCardMove` event to your own
1128
+ state. Render each card as a `RudiKanbanCard` inside `renderCard`. Card ids must be unique
1129
+ across all columns. Use `RudiTable` instead for non-draggable tabular data.
1130
+
1131
+ ```tsx
1132
+ <RudiKanbanBoard
1133
+ columns={columns}
1134
+ onCardMove={(e) => setColumns((prev) => moveCard(prev, e))}
1135
+ renderCard={(item) => <RudiKanbanCard key={item.id} id={item.id}>{String(item.title)}</RudiKanbanCard>}
1136
+ />
1137
+ ```
1138
+
1139
+ | Prop | Type | Default | Description |
1140
+ | --- | --- | --- | --- |
1141
+ | `columns` *(required)* | `RudiKanbanColumnData[]` | | Columns and their cards. The board is controlled: it never reorders them itself. |
1142
+ | `onCardMove` *(required)* | `(event: RudiKanbanCardMoveEvent) => void` | | Called once when a drag ends in a new position. Update `columns` here. Not called when the card is dropped where it started. |
1143
+ | `renderCard` *(required)* | `(item: RudiKanbanItem) => React.ReactNode` | | Renders one card. Return a `RudiKanbanCard` with the item's `id`, which makes it draggable. |
1144
+ | `getCardLabel` | `(item: RudiKanbanItem) => string` | | Names a card in drag announcements ("Picked up REF-1042 from Pending"). Defaults to its id. |
1145
+ | `className` | `string` | | Class merged onto the board's column container. |
1146
+
1147
+ #### RudiKanbanBoard.Column
1148
+
1149
+ A single column. The board renders these for you; use directly only when composing a custom layout inside the board's drag context.
1150
+
1151
+ | Prop | Type | Default | Description |
1152
+ | --- | --- | --- | --- |
1153
+ | `id` *(required)* | `string` | | Unique column id; the drop target id. |
1154
+ | `title` *(required)* | `string` | | Column heading and the region's accessible name. |
1155
+ | `items` *(required)* | `RudiKanbanItem[]` | | Cards in display order. The count is shown in the header. |
1156
+ | `renderCard` *(required)* | `(item: RudiKanbanItem) => React.ReactNode` | | Renders one card; return a `RudiKanbanCard`. |
1157
+ | `className` | `string` | | Class merged onto the column element. |
1158
+
1159
+ ### RudiKanbanColumn
1160
+
1161
+ One droppable column of sortable cards. `RudiKanbanBoard` renders these from its `columns` prop;
1162
+ use directly only inside a board's drag context (also available as `RudiKanbanBoard.Column`).
1163
+
1164
+ ```tsx
1165
+ <RudiKanbanColumn id="todo" title="To do" items={items} renderCard={renderCard} />
1166
+ ```
1167
+
1168
+ | Prop | Type | Default | Description |
1169
+ | --- | --- | --- | --- |
1170
+ | `id` *(required)* | `string` | | Unique column id; the drop target id. |
1171
+ | `title` *(required)* | `string` | | Column heading and the region's accessible name. |
1172
+ | `items` *(required)* | `RudiKanbanItem[]` | | Cards in display order. The count is shown in the header. |
1173
+ | `renderCard` *(required)* | `(item: RudiKanbanItem) => React.ReactNode` | | Renders one card; return a `RudiKanbanCard`. |
1174
+ | `className` | `string` | | Class merged onto the column element. |
1175
+
1176
+ ### RudiKanbanCard
1177
+
1178
+ A draggable card with a drag handle. Return it from `RudiKanbanBoard`'s `renderCard`, passing
1179
+ the item's `id`. Pass `label` so the handle is announced as "Move <label>".
1180
+
1181
+ ```tsx
1182
+ <RudiKanbanCard id={item.id} label={String(item.ref)}>{String(item.ref)}</RudiKanbanCard>
1183
+ ```
1184
+
1185
+ | Prop | Type | Default | Description |
1186
+ | --- | --- | --- | --- |
1187
+ | `id` *(required)* | `string` | | Matches the `id` of the card's `RudiKanbanItem`. |
1188
+ | `children` *(required)* | `React.ReactNode` | | Card content, shown beside the drag handle. |
1189
+ | `label` | `string` | | Human name for the card (e.g. its title or reference). Names the drag handle ("Move REF-1042") so screen-reader users hear which card they're on. Falls back to `id`. |
1190
+ | `className` | `string` | | Class merged onto the card element. |
1191
+
1192
+ ### RudiHeading
1193
+
1194
+ Semantic heading (`h1` to `h6`) whose visual size is set separately from its level, so the document outline stays correct while the look follows the design. Use `RudiText` for non-heading text. Not polymorphic: the element is always chosen by `level`. Other DOM props are spread onto the element.
1195
+
1196
+ ```tsx
1197
+ <RudiHeading level={2} size={4} tone="brand">
1198
+ Section title
1199
+ </RudiHeading>
1200
+ ```
1201
+
1202
+ | Prop | Type | Default | Description |
1203
+ | --- | --- | --- | --- |
1204
+ | `level` *(required)* | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | | Semantic level; picks the element (`1` renders `h1`, through `6` for `h6`) and the document outline. Keep levels in order. |
1205
+ | `children` *(required)* | `React.ReactNode` | | Heading content. |
1206
+ | `size` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | | Visual size on the same 1-6 scale, independent of `level`; matches `level` when omitted. |
1207
+ | `weight` | `RudiTypographyWeight` | | Font weight, overriding the size default. |
1208
+ | `tone` | `RudiTypographyTone` | | Semantic text color. |
1209
+ | `align` | `RudiTypographyAlign` | | Text alignment. |
1210
+ | `noMargin` | `boolean` | | Removes the element's default block margin. |
1211
+ | `className` | `string` | | Extra class names, merged with the built-in classes. |
1212
+
1213
+ `ref` forwards to `HTMLHeadingElement`. Spreads remaining props onto the DOM element (`AriaAttributes`, `DOMAttributes`, `HTMLAttributes`).
1214
+
1215
+ ### RudiText
1216
+
1217
+ Body-level text in one of five variants (body, body-sm, caption, overline, code). Use `RudiHeading` for headings and `RudiProse` for long-form content with its own rhythm. Polymorphic through `as`, which defaults to a `p`; other DOM props are spread onto the element.
1218
+
1219
+ ```tsx
1220
+ <RudiText variant="caption" tone="subtle">
1221
+ Last updated March 2026
1222
+ </RudiText>
1223
+ ```
1224
+
1225
+ | Prop | Type | Default | Description |
1226
+ | --- | --- | --- | --- |
1227
+ | `children` *(required)* | `React.ReactNode` | | Text content. |
1228
+ | `variant` | `'body' \| 'body-sm' \| 'caption' \| 'overline' \| 'code'` | `'body'` | Typographic role: `body` for paragraphs, `body-sm` for supporting text, `caption` for metadata, `overline` for uppercase labels, `code` for monospace values. |
1229
+ | `as` | `React.ElementType` | `'p'` | Element or component to render. Use `"span"` for inline text, or `"label"` and `"strong"` where the semantics call for them. |
1230
+ | `weight` | `RudiTypographyWeight` | | Font weight, overriding the variant default. |
1231
+ | `tone` | `RudiTypographyTone` | | Semantic text color. |
1232
+ | `align` | `RudiTypographyAlign` | | Text alignment. |
1233
+ | `noMargin` | `boolean` | | Removes the element's default block margin. |
1234
+ | `className` | `string` | | Extra class names, merged with the built-in classes. |
1235
+
1236
+ `ref` forwards to `HTMLElement`. Spreads remaining props onto the DOM element (`AllHTMLAttributes`, `AriaAttributes`, `DOMAttributes`, `HTMLAttributes`).
1237
+
1238
+ ### RudiProse
1239
+
1240
+ Wrapper that styles plain HTML children (paragraphs, headings, lists, links) with consistent typography and vertical rhythm. Use it for articles, documentation, and CMS output; use `RudiText` and `RudiHeading` when you compose individual pieces. Polymorphic through `as`; DOM props are spread onto the root.
1241
+
1242
+ ```tsx
1243
+ <RudiProse size="lg">
1244
+ <h2>Title</h2>
1245
+ <p>Body copy.</p>
1246
+ </RudiProse>
1247
+ ```
1248
+
1249
+ | Prop | Type | Default | Description |
1250
+ | --- | --- | --- | --- |
1251
+ | `children` *(required)* | `React.ReactNode` | | Long-form content, such as paragraphs, headings, lists, and quotes, as plain elements. |
1252
+ | `size` | `'sm' \| 'base' \| 'lg'` | `'base'` | Type scale for the whole block: `sm`, `base`, or `lg`. |
1253
+ | `as` | `React.ElementType` | `'div'` | Element or component to render as the root. |
1254
+ | `className` | `string` | | Extra class names, merged with the built-in classes. |
1255
+
1256
+ `ref` forwards to `HTMLElement`. Spreads remaining props onto the DOM element (`AriaAttributes`, `DOMAttributes`, `HTMLAttributes`).
1257
+
1258
+ ### RudiBox
1259
+
1260
+ Padded container with an optional border or inverted surface. Use it for cards, panels, and callouts; use `RudiStack` or `RudiCluster` to space the things inside it, and `RudiCenter` when you need a max-width rather than padding.
1261
+ Polymorphic through `as`; unrecognised DOM props (`id`, `aria-*`, `data-*`, handlers) are spread onto the root element, and `className` is merged with the built-in class, not replaced.
1262
+
1263
+ ```tsx
1264
+ <RudiBox padding="1.5rem" bordered>
1265
+ <RudiText>Panel content</RudiText>
1266
+ </RudiBox>
1267
+ ```
1268
+
1269
+ | Prop | Type | Default | Description |
1270
+ | --- | --- | --- | --- |
1271
+ | `padding` | `string` | | Padding on all four sides; any CSS length, such as `"1rem"` or `"var(--rudi-spacing-6)"`. Falls back to the `--rudi-layout-box-padding` token (1rem). |
1272
+ | `bordered` | `boolean` | `false` | Draws a 1px border with the themed border color and radius. |
1273
+ | `invert` | `boolean` | `false` | Swaps to the inverted surface and text colors (dark panel on a light theme, and the reverse). |
1274
+ | `sticky` | `boolean \| string` | `false` | Stick to the top of the scroll container while scrolling. A string sets the top offset (e.g. `"1rem"`). |
1275
+ | `as` | `React.ElementType` | `'div'` | Element or component to render as the root. |
1276
+ | `children` | `React.ReactNode` | | Content placed inside the padded container. |
1277
+ | `className` | `string` | | Extra class names, merged with the component's own classes. |
1278
+
1279
+ `ref` forwards to `HTMLElement`. Spreads remaining props onto the DOM element (`AriaAttributes`, `DOMAttributes`, `HTMLAttributes`).
1280
+
1281
+ ### RudiStack
1282
+
1283
+ Vertical list of children with consistent spacing. Choose it for forms, card content, and page sections; use `RudiCluster` for items that run horizontally and wrap, and `RudiSwitcher` for a row that collapses to a column.
1284
+ Polymorphic through `as` (use `"ul"` or `"ol"` for a list; bullets and indent are removed); unrecognised DOM props are spread onto the root element, and `className` is merged with the built-in class, not replaced.
1285
+
1286
+ ```tsx
1287
+ <RudiStack space="1rem">
1288
+ <RudiInput label="Name" />
1289
+ <RudiInput label="Email" />
1290
+ </RudiStack>
1291
+ ```
1292
+
1293
+ | Prop | Type | Default | Description |
1294
+ | --- | --- | --- | --- |
1295
+ | `space` | `string` | | CSS spacing value. Defaults to --rudi-layout-stack-space-default token. |
1296
+ | `recursive` | `boolean` | `false` | Apply spacing recursively to all nested elements, not just direct children. |
1297
+ | `splitAfter` | `number` | | 1-based index of the child after which to insert an auto margin, splitting the stack. |
1298
+ | `as` | `React.ElementType` | `'div'` | HTML element to render. |
1299
+ | `children` | `React.ReactNode` | | Items to space out vertically. |
1300
+ | `className` | `string` | | Extra class names, merged with the component's own classes. |
1301
+
1302
+ `ref` forwards to `HTMLElement`. Spreads remaining props onto the DOM element (`AriaAttributes`, `DOMAttributes`, `HTMLAttributes`).
1303
+
1304
+ ### RudiCluster
1305
+
1306
+ Horizontal row of items that wraps onto new lines when space runs out. Choose it for tags, button groups, and breadcrumbs. Use `RudiStack` for a vertical list, and `RudiSwitcher` when a row should collapse to a single column as a whole instead of wrapping item by item.
1307
+ Polymorphic through `as`; unrecognised DOM props (`id`, `aria-*`, `data-*`, handlers) are spread onto the root element, and `className` is merged with the built-in class, not replaced.
1308
+
1309
+ ```tsx
1310
+ <RudiCluster space="0.5rem" justify="flex-end">
1311
+ <RudiButton onPress={cancel}>Cancel</RudiButton>
1312
+ <RudiButton onPress={save}>Save</RudiButton>
1313
+ </RudiCluster>
1314
+ ```
1315
+
1316
+ | Prop | Type | Default | Description |
1317
+ | --- | --- | --- | --- |
1318
+ | `space` | `string` | | Gap between items, both horizontally and between wrapped rows; any CSS length. Falls back to the `--rudi-layout-cluster-space` token (1rem). |
1319
+ | `justify` | `\| 'flex-start' \| 'flex-end' \| 'center' \| 'space-between' \| 'space-around'` | | Horizontal distribution of items along each row (`justify-content`). Defaults to `flex-start` in CSS. |
1320
+ | `align` | `'flex-start' \| 'flex-end' \| 'center' \| 'baseline' \| 'stretch'` | | Vertical alignment of items within each row (`align-items`). Defaults to `center` in CSS. |
1321
+ | `as` | `React.ElementType` | `'div'` | Element or component to render as the root. Use `"ul"` or `"ol"` for a list; bullets and indent are removed. |
1322
+ | `children` | `React.ReactNode` | | Items to lay out in a row. |
1323
+ | `className` | `string` | | Extra class names, merged with the component's own classes. |
1324
+
1325
+ `ref` forwards to `HTMLElement`. Spreads remaining props onto the DOM element (`AriaAttributes`, `DOMAttributes`, `HTMLAttributes`).
1326
+
1327
+ ### RudiGrid
1328
+
1329
+ Responsive grid of equal-width columns that adds or drops columns as the container width changes, with no breakpoints. Choose it for card grids, galleries, and dashboards of similar items. Use `RudiSwitcher` for a single row that stacks all at once, and `RudiSidebar` for two panels of different widths.
1330
+ Polymorphic through `as`; unrecognised DOM props (`id`, `aria-*`, `data-*`, handlers) are spread onto the root element, and `className` is merged with the built-in class, not replaced.
1331
+
1332
+ ```tsx
1333
+ <RudiGrid minCellWidth="16rem" space="1rem">
1334
+ <RudiCard>One</RudiCard>
1335
+ <RudiCard>Two</RudiCard>
1336
+ </RudiGrid>
1337
+ ```
1338
+
1339
+ | Prop | Type | Default | Description |
1340
+ | --- | --- | --- | --- |
1341
+ | `minCellWidth` | `string` | | Minimum width of each column before the grid fits fewer columns; any CSS length, capped at 100% of the container. Falls back to the `--rudi-layout-grid-min-cell` token (15rem). |
1342
+ | `space` | `string` | | Gap between rows and columns; any CSS length. Falls back to the `--rudi-layout-grid-space` token (1.5rem). |
1343
+ | `as` | `React.ElementType` | `'div'` | Element or component to render as the root. Use `"ul"` or `"ol"` for a list; bullets and indent are removed. |
1344
+ | `children` | `React.ReactNode` | | Items, one per cell. |
1345
+ | `className` | `string` | | Extra class names, merged with the component's own classes. |
1346
+
1347
+ `ref` forwards to `HTMLElement`. Spreads remaining props onto the DOM element (`AriaAttributes`, `DOMAttributes`, `HTMLAttributes`).
1348
+
1349
+ ### RudiSidebar
1350
+
1351
+ Two-panel layout where one panel has a set width and the other fills the rest, wrapping to a column when the content would drop below `contentMin`. Choose it for navigation or filters beside content. Use `RudiSwitcher` for panels of equal weight, and `RudiAppShell` for the application frame.
1352
+ Polymorphic through `as`; unrecognised DOM props (`id`, `aria-*`, `data-*`, handlers) are spread onto the root element, and `className` is merged with the built-in class, not replaced.
1353
+
1354
+ ```tsx
1355
+ <RudiSidebar sideWidth="16rem">
1356
+ <aside>Filters</aside>
1357
+ <main>Results</main>
1358
+ </RudiSidebar>
1359
+ ```
1360
+
1361
+ | Prop | Type | Default | Description |
1362
+ | --- | --- | --- | --- |
1363
+ | `side` | `'left' \| 'right'` | `'left'` | Which edge the sidebar sits on. The sidebar is the first child when `"left"` and the last child when `"right"`. |
1364
+ | `sideWidth` | `string` | | Preferred width of the sidebar; any CSS length. Falls back to the `--rudi-layout-sidebar-width` token (20rem). |
1365
+ | `contentMin` | `string` | | Minimum width of the content child, as a CSS length or percentage, before the two panels wrap into a column. Falls back to the `--rudi-layout-sidebar-content-min` token (50%). |
1366
+ | `space` | `string` | | Gap between the two panels, including after they wrap; any CSS length. Falls back to the `--rudi-layout-sidebar-space` token (1.5rem). |
1367
+ | `noStretch` | `boolean` | `false` | Keeps each panel at its own content height instead of stretching to match the taller one. |
1368
+ | `as` | `React.ElementType` | `'div'` | Element or component to render as the root. |
1369
+ | `children` | `React.ReactNode` | | Exactly two children: the sidebar and the main content, in DOM order matching `side`. |
1370
+ | `className` | `string` | | Extra class names, merged with the component's own classes. |
1371
+
1372
+ `ref` forwards to `HTMLElement`. Spreads remaining props onto the DOM element (`AriaAttributes`, `DOMAttributes`, `HTMLAttributes`).
1373
+
1374
+ ### RudiCenter
1375
+
1376
+ Horizontally centers its content in a column capped at a maximum width. Use it for article text, hero copy, and page-width wrappers; use `RudiBox` for padding and `RudiCover` for vertical centering. The max width is added to the gutters because the box uses `content-box` sizing.
1377
+ Polymorphic through `as`; unrecognised DOM props (`id`, `aria-*`, `data-*`, handlers) are spread onto the root element, and `className` is merged with the built-in class, not replaced.
1378
+
1379
+ ```tsx
1380
+ <RudiCenter maxWidth="40rem">
1381
+ <RudiProse>...</RudiProse>
1382
+ </RudiCenter>
1383
+ ```
1384
+
1385
+ | Prop | Type | Default | Description |
1386
+ | --- | --- | --- | --- |
1387
+ | `maxWidth` | `string` | | Maximum content width; any CSS length, such as `"45rem"`. Falls back to the `--rudi-layout-center-max-width` token (60rem). |
1388
+ | `gutters` | `string` | | Minimum inline padding on each side, so content never touches the viewport edge; any CSS length. Falls back to the `--rudi-layout-center-gutters` token (1rem). |
1389
+ | `intrinsic` | `boolean` | `false` | Also centers each child horizontally by its own content width, as a column flex container. |
1390
+ | `as` | `React.ElementType` | `'div'` | Element or component to render as the root. |
1391
+ | `children` | `React.ReactNode` | | Content to center. |
1392
+ | `className` | `string` | | Extra class names, merged with the component's own classes. |
1393
+
1394
+ `ref` forwards to `HTMLElement`. Spreads remaining props onto the DOM element (`AriaAttributes`, `DOMAttributes`, `HTMLAttributes`).
1395
+
1396
+ ### RudiCover
1397
+
1398
+ Full-height column that pins an optional first and last child to the top and bottom and centers `RudiCover.Centered` in between. Use it for hero sections and login pages; use `RudiCenter` for horizontal centering only.
1399
+ Polymorphic through `as`; unrecognised DOM props (`id`, `aria-*`, `data-*`, handlers) are spread onto the root element, and `className` is merged with the built-in class, not replaced.
1400
+
1401
+ ```tsx
1402
+ <RudiCover minHeight="100vh">
1403
+ <RudiTopBar />
1404
+ <RudiCover.Centered>
1405
+ <RudiHeading level={1}>Sign in</RudiHeading>
1406
+ </RudiCover.Centered>
1407
+ </RudiCover>
1408
+ ```
1409
+
1410
+ | Prop | Type | Default | Description |
1411
+ | --- | --- | --- | --- |
1412
+ | `minHeight` | `string` | | Minimum block size of the cover; any CSS length. Falls back to the `--rudi-layout-cover-min-height` token (100vh). |
1413
+ | `space` | `string` | | Minimum vertical space between the cover's children; any CSS length. Falls back to the `--rudi-layout-cover-space` token (1.5rem). |
1414
+ | `as` | `React.ElementType` | `'div'` | Element or component to render as the root. |
1415
+ | `children` | `React.ReactNode` | | Optional header and footer elements, plus one `RudiCover.Centered` child. |
1416
+ | `className` | `string` | | Extra class names, merged with the component's own classes. |
1417
+
1418
+ `ref` forwards to `HTMLElement`. Spreads remaining props onto the DOM element (`AriaAttributes`, `DOMAttributes`, `HTMLAttributes`).
1419
+
1420
+ #### RudiCover.Centered
1421
+
1422
+ The child centered vertically between the cover's other children. Use at most one per cover.
1423
+
1424
+ | Prop | Type | Default | Description |
1425
+ | --- | --- | --- | --- |
1426
+ | `as` | `React.ElementType` | `'div'` | Element or component to render as the root. |
1427
+ | `children` | `React.ReactNode` | | The principal content to center vertically. |
1428
+ | `className` | `string` | | Extra class names, merged with the component's own classes. |
1429
+
1430
+ `ref` forwards to `HTMLElement`. Spreads remaining props onto the DOM element (`AriaAttributes`, `DOMAttributes`, `HTMLAttributes`).
1431
+
1432
+ ### RudiSwitcher
1433
+
1434
+ Row of children that switches to a single column, all at once, when the container is narrower than `threshold`. Choose it for form field groups and pricing cards. Use `RudiCluster` when items should wrap one by one, and `RudiGrid` for many equal cells in several rows.
1435
+ Polymorphic through `as`; unrecognised DOM props (`id`, `aria-*`, `data-*`, handlers) are spread onto the root element, and `className` is merged with the built-in class, not replaced.
1436
+
1437
+ ```tsx
1438
+ <RudiSwitcher threshold="40rem">
1439
+ <RudiInput label="First name" />
1440
+ <RudiInput label="Last name" />
1441
+ </RudiSwitcher>
1442
+ ```
1443
+
1444
+ | Prop | Type | Default | Description |
1445
+ | --- | --- | --- | --- |
1446
+ | `threshold` | `string` | | Container width below which the children stack into a single column and above which they share one row; any CSS length. Falls back to the `--rudi-layout-switcher-threshold` token (30rem). |
1447
+ | `space` | `string` | | Gap between children, in both row and column layouts; any CSS length. Falls back to the `--rudi-layout-switcher-space` token (1.5rem). |
1448
+ | `limit` | `number` | | Maximum number of children that can share a row. When there are more children than `limit`, they all stack in a single column, each at full width, at any container width. Unset by default, so only `threshold` decides. |
1449
+ | `as` | `React.ElementType` | `'div'` | Element or component to render as the root. |
1450
+ | `children` | `React.ReactNode` | | Items that sit in a row or stack together. |
1451
+ | `className` | `string` | | Extra class names, merged with the component's own classes. |
1452
+
1453
+ `ref` forwards to `HTMLElement`. Spreads remaining props onto the DOM element (`AriaAttributes`, `DOMAttributes`, `HTMLAttributes`).
1454
+
1455
+ ### RudiAppShell
1456
+
1457
+ Application frame with a sidebar and a content area; below 900px the sidebar becomes a drawer that Escape and the backdrop close. Compose it from `RudiAppShell.Sidebar` and `RudiAppShell.Content` (put `RudiTopBar` and `RudiAppShell.Main` inside Content). Use `RudiSidebar` for a simple two-panel layout inside a page instead. The parts throw if rendered outside it. Open state is uncontrolled unless `isSidebarOpen` is set. Other DOM props go on the root `div`.
1458
+
1459
+ ```tsx
1460
+ <RudiAppShell>
1461
+ <RudiAppShell.Sidebar aria-label="Main">
1462
+ <RudiNavItem label="Home" icon="mdi:home" href="/" />
1463
+ </RudiAppShell.Sidebar>
1464
+ <RudiAppShell.Content>
1465
+ <RudiTopBar start={<RudiAppShell.MenuButton />} />
1466
+ <RudiAppShell.Main>Page</RudiAppShell.Main>
1467
+ </RudiAppShell.Content>
1468
+ </RudiAppShell>
1469
+ ```
1470
+
1471
+ | Prop | Type | Default | Description |
1472
+ | --- | --- | --- | --- |
1473
+ | `children` *(required)* | `React.ReactNode` | | `RudiAppShell.Sidebar` and `RudiAppShell.Content`, plus any other layout children. |
1474
+ | `isSidebarOpen` | `boolean` | | Controlled open state of the responsive sidebar drawer, which is only visible below the 900px breakpoint. Pair with `onSidebarOpenChange`. |
1475
+ | `onSidebarOpenChange` | `(open: boolean) => void` | | Called when the drawer requests an open-state change. |
1476
+ | `defaultSidebarOpen` | `boolean` | `false` | Initial open state when uncontrolled. |
1477
+ | `className` | `string` | | Extra class names, merged with the built-in classes. |
1478
+
1479
+ `ref` forwards to `HTMLDivElement`. Spreads remaining props onto the DOM element (`AriaAttributes`, `DOMAttributes`, `HTMLAttributes`).
1480
+
1481
+ #### RudiAppShell.Sidebar
1482
+
1483
+ Navigation drawer (an `aside`) shown inline on wide screens and as a slide-over below 900px; renders its own backdrop.
1484
+
1485
+ | Prop | Type | Default | Description |
1486
+ | --- | --- | --- | --- |
1487
+ | `children` *(required)* | `React.ReactNode` | | Navigation and other sidebar content, such as `RudiNavItem` entries. |
1488
+ | `width` | `string` | | Overrides the sidebar width; any CSS length. Falls back to the `--rudi-component-app-shell-sidebar-width` token. |
1489
+ | `aria-label` | `string` | `'Sidebar'` | Accessible name of the `aside` landmark; give it a specific name when the page has other complementary landmarks. |
1490
+ | `className` | `string` | | Extra class names, merged with the built-in classes. |
1491
+
1492
+ Spreads remaining props onto the DOM element (`AriaAttributes`, `DOMAttributes`, `HTMLAttributes`).
1493
+
1494
+ #### RudiAppShell.Content
1495
+
1496
+ Column beside the sidebar that holds the top bar and the main area.
1497
+
1498
+ | Prop | Type | Default | Description |
1499
+ | --- | --- | --- | --- |
1500
+ | `children` *(required)* | `React.ReactNode` | | The top bar and `RudiAppShell.Main`. |
1501
+ | `className` | `string` | | Extra class names, merged with the built-in classes. |
1502
+
1503
+ Spreads remaining props onto the DOM element (`AriaAttributes`, `DOMAttributes`, `HTMLAttributes`).
1504
+
1505
+ #### RudiAppShell.Main
1506
+
1507
+ The page's `main` landmark; centers its children in a padded column with a max width.
1508
+
1509
+ | Prop | Type | Default | Description |
1510
+ | --- | --- | --- | --- |
1511
+ | `children` *(required)* | `React.ReactNode` | | Page content; it is wrapped in an inner column limited by `maxWidth`. |
1512
+ | `maxWidth` | `string` | | Max width of the centered content column; any CSS length. Falls back to the `--rudi-component-app-shell-main-max-width` token. |
1513
+ | `padding` | `string` | | Padding around the content column; any CSS length. Falls back to the `--rudi-component-app-shell-main-padding` token. |
1514
+ | `className` | `string` | | Extra class names, merged with the built-in classes. |
1515
+
1516
+ Spreads remaining props onto the DOM element (`AriaAttributes`, `DOMAttributes`, `HTMLAttributes`).
1517
+
1518
+ #### RudiAppShell.MenuButton
1519
+
1520
+ Hamburger button that toggles the sidebar drawer; place it in the top bar's `start` slot. Escape returns focus to it.
1521
+
1522
+ | Prop | Type | Default | Description |
1523
+ | --- | --- | --- | --- |
1524
+ | `aria-label` | `string` | `'Open navigation'` | Accessible name of the button. |
1525
+ | `icon` | `string` | `'lucide:menu'` | Iconify icon name for the hamburger. |
1526
+ | `className` | `string` | | Extra class names for the wrapper element, merged with the built-in classes. |
1527
+
1528
+ ### RudiTopBar
1529
+
1530
+ Horizontal application bar with start, center, and end slots and an optional announcement strip above. Use it at the top of `RudiAppShell.Content` or a page; use `RudiPageHeader` for a page title. Each slot is rendered only when provided. Polymorphic through `as` (default `header`); DOM props are spread onto the root.
1531
+
1532
+ ```tsx
1533
+ <RudiTopBar start={<RudiBrand name="Acme" />} end={<RudiButton onPress={signOut}>Sign out</RudiButton>} />
1534
+ ```
1535
+
1536
+ | Prop | Type | Default | Description |
1537
+ | --- | --- | --- | --- |
1538
+ | `start` | `React.ReactNode` | | Content pinned to the inline-start of the bar. |
1539
+ | `end` | `React.ReactNode` | | Content pinned to the inline-end of the bar. |
1540
+ | `announcement` | `React.ReactNode` | | Optional strip rendered above the main row, e.g. an announcement. |
1541
+ | `sticky` | `boolean` | `true` | Whether the bar sticks to the top of its scroll container. |
1542
+ | `as` | `React.ElementType` | `'header'` | Element to render. Defaults to `header`. |
1543
+ | `children` | `React.ReactNode` | | Fills the growing center of the main row (brand, nav, title). |
1544
+ | `className` | `string` | | Extra class names, merged with the built-in classes. |
1545
+
1546
+ `ref` forwards to `HTMLElement`. Spreads remaining props onto the DOM element (`AriaAttributes`, `DOMAttributes`, `HTMLAttributes`).
1547
+
1548
+ ### RudiDescriptionList
1549
+
1550
+ Semantic `dl` for read-only key-value data such as record details. Use a table for data with several attributes per row.
1551
+
1552
+ ```tsx
1553
+ <RudiDescriptionList
1554
+ layout="inline"
1555
+ items={[{ term: 'Status', description: 'Shipped' }, { term: 'Carrier', description: 'DHL' }]}
1556
+ />
1557
+ ```
1558
+
1559
+ | Prop | Type | Default | Description |
1560
+ | --- | --- | --- | --- |
1561
+ | `items` *(required)* | `RudiDescriptionListItem[]` | | Term and description pairs, in display order. |
1562
+ | `layout` | `'stacked' \| 'inline'` | `'stacked'` | `stacked` puts the term above its description. `inline` puts them side by side in two columns, and collapses back to stacked when the list's own width is narrow (a container query, not the viewport). |
1563
+ | `columns` | `number` | `1` | Maximum number of columns for the `stacked` layout. Fewer are used when the container is narrow. |
1564
+ | `dividers` | `boolean` | `false` | Draws a hairline under each row. |
1565
+ | `className` | `string` | | Extra class names, merged with the component's own classes rather than replacing them. |
1566
+
1567
+ ### RudiPageHeader
1568
+
1569
+ Title block for a page: heading with optional eyebrow, subtitle, metadata, and an actions slot. Use it once at the top of a page; use `RudiSectionHeader` for sections within a page. The title is visually sized 2 whatever `headingLevel` is. Other DOM props go on the root `div`.
1570
+
1571
+ ```tsx
1572
+ <RudiPageHeader title="Projects" subtitle="12 active" actions={<RudiButton onPress={create}>New</RudiButton>} />
1573
+ ```
1574
+
1575
+ | Prop | Type | Default | Description |
1576
+ | --- | --- | --- | --- |
1577
+ | `title` *(required)* | `React.ReactNode` | | Page title, rendered as the heading. |
1578
+ | `subtitle` | `React.ReactNode` | | Supporting line below the title, in caption text. |
1579
+ | `eyebrow` | `React.ReactNode` | | Content above the title, e.g. a breadcrumb or a small overline. Rendered in a `div`. |
1580
+ | `meta` | `React.ReactNode` | | Content below the subtitle, e.g. a row of badges or key facts. Rendered in a `div`. |
1581
+ | `actions` | `React.ReactNode` | | Content pinned to the inline-end, e.g. primary page actions. |
1582
+ | `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` | Heading level for the title. Defaults to 1. |
1583
+ | `className` | `string` | | Extra class names, merged with the built-in classes. |
1584
+ | `children` | `ReactNode` | | Content. |
1585
+
1586
+ `ref` forwards to `HTMLDivElement`. Spreads remaining props onto the DOM element (`AriaAttributes`, `DOMAttributes`, `HTMLAttributes`).
1587
+
1588
+ ### RudiSectionHeader
1589
+
1590
+ Heading row for a section of a page, with an optional description and an action slot. Use `RudiPageHeader` for the page title instead. The title is visually sized 5 whatever `headingLevel` is. Other DOM props go on the root `div`.
1591
+
1592
+ ```tsx
1593
+ <RudiSectionHeader title="Recent activity" action={<RudiButton onPress={showAll}>See all</RudiButton>} />
1594
+ ```
1595
+
1596
+ | Prop | Type | Default | Description |
1597
+ | --- | --- | --- | --- |
1598
+ | `title` *(required)* | `React.ReactNode` | | Section title, rendered as the heading. |
1599
+ | `description` | `React.ReactNode` | | Supporting text below the title, in small body text. |
1600
+ | `action` | `React.ReactNode` | | Content pinned to the inline-end, e.g. a "see all" link or button. |
1601
+ | `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `2` | Heading level for the title. Defaults to 2. |
1602
+ | `className` | `string` | | Extra class names, merged with the built-in classes. |
1603
+ | `children` | `ReactNode` | | Content. |
1604
+
1605
+ `ref` forwards to `HTMLDivElement`. Spreads remaining props onto the DOM element (`AriaAttributes`, `DOMAttributes`, `HTMLAttributes`).
1606
+
1607
+ ### RudiRouterProvider
1608
+
1609
+ Connects Rudi links (`RudiLink`, `RudiNavItem`, `RudiBreadcrumb`) to your router for client-side
1610
+ navigation. Pass your router's `navigate` function, and optionally `useHref` for base paths.
1611
+
1612
+ ```tsx
1613
+ const navigate = useNavigate()
1614
+ <RudiRouterProvider navigate={navigate} useHref={useHref}>…</RudiRouterProvider>
1615
+ ```
1616
+
1617
+ Without it, links work as ordinary full-page links.
1618
+
1619
+ Inherited from React Aria (types and descriptions in `components.json`): `navigate`, `children`, `useHref`.
1620
+
1621
+ ### RudiBrand
1622
+
1623
+ Logo lockup: a mark plus the product name, optionally linking home. Use it in `RudiTopBar` or the sidebar header. `name` is the accessible name even when `hideName` is set. It does not spread DOM props.
1624
+
1625
+ ```tsx
1626
+ <RudiBrand name="Acme" mark={<AcmeLogo />} href="/" />
1627
+ ```
1628
+
1629
+ | Prop | Type | Default | Description |
1630
+ | --- | --- | --- | --- |
1631
+ | `name` *(required)* | `string` | | Product or company name. Always the accessible name; visible unless `hideName`. |
1632
+ | `mark` | `React.ReactNode` | | Logo mark (an icon, `<svg>` or `<img>`). Decorative: hidden from assistive tech. |
1633
+ | `hideName` | `boolean` | `false` | Hide the visible name when the mark already includes the wordmark. |
1634
+ | `href` | `string` | | Makes the lockup a link (usually home). Routes client-side under `RudiRouterProvider`. |
1635
+ | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size of the mark and name. |
1636
+ | `className` | `string` | | Extra class names, merged with the built-in classes. |
1637
+
1638
+ ### RudiForm
1639
+
1640
+ A `<form>` that collects submitted values as `FormData`, never reloads the page, and shows a focusable error summary when `errors` is non-empty. Validate in `onSubmit` and pass the messages back via `errors`; field-level `errorMessage` props are set separately on each field.
1641
+
1642
+ ```tsx
1643
+ <RudiForm onSubmit={(data) => save(data)} errors={errors}>
1644
+ <RudiInput label="Name" name="name" />
1645
+ <RudiButton type="submit">Save</RudiButton>
1646
+ </RudiForm>
1647
+ ```
1648
+
1649
+ | Prop | Type | Default | Description |
1650
+ | --- | --- | --- | --- |
1651
+ | `children` *(required)* | `React.ReactNode` | | The form's fields and buttons. |
1652
+ | `onSubmit` | `(data: FormData, event: React.FormEvent<HTMLFormElement>) => void` | | Called on submit with the form's data. The page never reloads. |
1653
+ | `errors` | `string[]` | `[]` | Problems to fix, shown as a summary at the top. After each submit that leaves problems, the summary receives focus so keyboard and screen-reader users land on it. Updating `errors` while the user edits never moves focus. |
1654
+ | `errorTitle` | `(count: number) => string` | `defaultTitle` | Builds the summary heading from the error count. |
1655
+ | `className` | `string` | | Extra class names for the form element, merged with the component's own classes. |
1656
+
1657
+ `ref` forwards to `HTMLFormElement`. Spreads remaining props onto the DOM element (`AriaAttributes`, `DOMAttributes`, `FormHTMLAttributes`, `HTMLAttributes`).
1658
+
1659
+ ### RudiTabs
1660
+
1661
+ Root of the tabs compound. Owns selection (`selectedKey` / `defaultSelectedKey` /
1662
+ `onSelectionChange`). Compose with `RudiTabList`, `RudiTab` and `RudiTabPanel`. Uncontrolled
1663
+ unless `selectedKey` is set. Keys are the string `id`s of the tabs.
1664
+
1665
+ ```tsx
1666
+ <RudiTabs defaultSelectedKey="all">
1667
+ <RudiTabList aria-label="Shipments"><RudiTab id="all">All</RudiTab></RudiTabList>
1668
+ <RudiTabPanel id="all">All shipments</RudiTabPanel>
1669
+ </RudiTabs>
1670
+ ```
1671
+
1672
+ | Prop | Type | Default | Description |
1673
+ | --- | --- | --- | --- |
1674
+ | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout and arrow-key axis. Lives on the root (not the list) because React Aria reads it from `Tabs`; vertical places the list beside the panels. |
1675
+ | `className` | `string` | | Class merged onto the root element. |
1676
+
1677
+ Inherited from React Aria (types and descriptions in `components.json`): `children`, `isDisabled`, `id`, `aria-label`, `aria-labelledby`, `aria-describedby`, `aria-details`, `disabledKeys`, `onSelectionChange`, `selectedKey`, `defaultSelectedKey`, `keyboardActivation`.
1678
+
1679
+ Also accepts React Aria's global DOM props (`DOMRenderProps`, `GlobalDOMAttributes`, `GlobalDOMEvents`, `SlotProps`).
1680
+
1681
+ ### RudiTabList
1682
+
1683
+ Container for the `RudiTab`s inside `RudiTabs`. `aria-label` is required because the list is a
1684
+ `tablist` landmark. Render the matching `RudiTabPanel`s as siblings of the list, not inside it.
1685
+
1686
+ ```tsx
1687
+ <RudiTabList aria-label="Shipment status" variant="pill">
1688
+ <RudiTab id="all">All</RudiTab>
1689
+ </RudiTabList>
1690
+ ```
1691
+
1692
+ | Prop | Type | Default | Description |
1693
+ | --- | --- | --- | --- |
1694
+ | `aria-label` *(required)* | `string` | | Accessible name for the tab list, e.g. "Shipment status". |
1695
+ | `variant` | `'underline' \| 'pill'` | `'underline'` | Visual treatment of the tabs. |
1696
+ | `className` | `string` | | Class merged onto the tab list element. |
1697
+
1698
+ Inherited from React Aria (types and descriptions in `components.json`): `children`, `aria-labelledby`, `aria-describedby`, `aria-details`, `items`, `dependencies`.
1699
+
1700
+ Also accepts React Aria's global DOM props (`DOMRenderProps`, `GlobalDOMAttributes`, `GlobalDOMEvents`).
1701
+
1702
+ ### RudiTab
1703
+
1704
+ A single tab in a `RudiTabList`. Its `id` must match the `id` of the `RudiTabPanel` it controls.
1705
+
1706
+ ```tsx
1707
+ <RudiTab id="pending" icon="mdi:clock-outline" badge={7}>Pending</RudiTab>
1708
+ ```
1709
+
1710
+ | Prop | Type | Default | Description |
1711
+ | --- | --- | --- | --- |
1712
+ | `id` *(required)* | `string` | | Unique key; matches the `id` of the corresponding `RudiTabPanel`. |
1713
+ | `children` *(required)* | `ReactNode` | | Tab label. |
1714
+ | `icon` | `string` | | Iconify icon name rendered before the label. |
1715
+ | `badge` | `ReactNode` | | Trailing content after the label, e.g. a count `RudiBadge`. Part of the accessible name. |
1716
+ | `className` | `string` | | Class merged onto the tab element. |
1717
+
1718
+ Inherited from React Aria (types and descriptions in `components.json`): `isDisabled`, `onPress`, `onPressStart`, `onPressEnd`, `onPressChange`, `onPressUp`, `onClick`, `onFocus`, `onBlur`, `onFocusChange`, `href`, `target`, `rel`, `aria-label`, `aria-labelledby`, `aria-describedby`, `aria-details`, `download`, `hrefLang`, `ping`, `referrerPolicy`, `routerOptions`, `onHoverStart`, `onHoverEnd`, `onHoverChange`.
1719
+
1720
+ Also accepts React Aria's global DOM props (`GlobalDOMAttributes`, `GlobalDOMEvents`, `PossibleLinkDOMRenderProps`).
1721
+
1722
+ ### RudiTabPanel
1723
+
1724
+ Content shown when its tab is selected. Only the selected panel is rendered. Its `id` must match
1725
+ a `RudiTab` `id`.
1726
+
1727
+ ```tsx
1728
+ <RudiTabPanel id="all">All shipments</RudiTabPanel>
1729
+ ```
1730
+
1731
+ | Prop | Type | Default | Description |
1732
+ | --- | --- | --- | --- |
1733
+ | `id` *(required)* | `string` | | Must match the `id` of the `RudiTab` that controls this panel. |
1734
+ | `className` | `string` | | Class merged onto the panel element. |
1735
+
1736
+ Inherited from React Aria (types and descriptions in `components.json`): `children`, `aria-label`, `aria-labelledby`, `aria-describedby`, `aria-details`, `shouldForceMount`.
1737
+
1738
+ Also accepts React Aria's global DOM props (`DOMRenderProps`, `GlobalDOMAttributes`, `GlobalDOMEvents`).
1739
+
1740
+ ### RudiEmptyState
1741
+
1742
+ Placeholder for a view, table, or card with no content, explaining why and offering a next step. Forwards its ref to the root `div`.
1743
+ The title renders as a heading, so set `headingLevel` to fit the surrounding outline.
1744
+
1745
+ ```tsx
1746
+ <RudiEmptyState
1747
+ icon="lucide:inbox"
1748
+ title="No shipments yet"
1749
+ description="Shipments appear here once an order is placed."
1750
+ action={<RudiButton onPress={create}>New order</RudiButton>}
1751
+ />
1752
+ ```
1753
+
1754
+ | Prop | Type | Default | Description |
1755
+ | --- | --- | --- | --- |
1756
+ | `title` *(required)* | `string` | | Short statement of what is empty, e.g. "No shipments yet". |
1757
+ | `icon` | `string` | | Iconify icon name shown above the title. Decorative. |
1758
+ | `description` | `ReactNode` | | Supporting text explaining why, or what to do next. |
1759
+ | `action` | `ReactNode` | | Call to action, e.g. a `RudiButton`. |
1760
+ | `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `3` | Semantic heading level for the title. |
1761
+ | `size` | `'sm' \| 'md'` | `'md'` | `sm` for table cells and cards, `md` for page sections. |
1762
+ | `className` | `string` | | Extra class names, merged with the component's own classes rather than replacing them. |
1763
+
1764
+ `ref` forwards to `HTMLDivElement`.
1765
+
1766
+ ### RudiComboBox
1767
+
1768
+ A searchable select: a text input that filters a list of options by case- and accent-insensitive substring
1769
+ match. Options are `RudiOption` elements, the same as `RudiSelect`; prefer `RudiSelect` for short lists.
1770
+ `label` is required. The text in the input, not the selected key, is what a `name`d form field submits.
1771
+
1772
+ ```tsx
1773
+ <RudiComboBox label="City" items={cities} onSelectionChange={setCity}>
1774
+ {(c) => <RudiOption key={c.id}>{c.name}</RudiOption>}
1775
+ </RudiComboBox>
1776
+ ```
1777
+
1778
+ | Prop | Type | Default | Description |
1779
+ | --- | --- | --- | --- |
1780
+ | `label` *(required)* | `string` | | Visible label. Required for accessibility. |
1781
+ | `items` *(required)* | `Iterable<T>` | | The options. Render each with `RudiOption`; give rich content a `textValue` so it can be filtered. |
1782
+ | `children` *(required)* | `(item: T) => ReactNode` | | Render function returning a `RudiOption` for each item. |
1783
+ | `selectedKey` | `Key \| null` | | The selected option key (controlled). |
1784
+ | `defaultSelectedKey` | `Key \| null` | | The initially selected option key (uncontrolled). |
1785
+ | `onSelectionChange` | `(key: Key \| null) => void` | | Called with the newly selected key, or `null` when the selection is cleared. |
1786
+ | `inputValue` | `string` | | The text in the input (controlled). |
1787
+ | `defaultInputValue` | `string` | | The initial text in the input (uncontrolled). |
1788
+ | `onInputChange` | `(value: string) => void` | | Called with the input text whenever it changes. |
1789
+ | `placeholder` | `string` | | Hint text shown in the input while it is empty. |
1790
+ | `description` | `string` | | Help text under the field. Hidden while `errorMessage` is shown. |
1791
+ | `errorMessage` | `string` | | Error text shown under the field. Setting it marks the field invalid. |
1792
+ | `isRequired` | `boolean` | `false` | Marks the field required and adds an asterisk to the label. |
1793
+ | `isDisabled` | `boolean` | `false` | Disables the input and the chevron button. |
1794
+ | `name` | `string` | | Form field name. The input's text is submitted under this name. |
1795
+ | `menuTrigger` | `'focus' \| 'input' \| 'manual'` | `'input'` | What opens the list: typing (`input`), focusing the field (`focus`), or only the arrow keys / chevron button (`manual`). |
1796
+ | `allowsCustomValue` | `boolean` | | Keep typed text that matches no option instead of reverting to the selected option on blur. |
1797
+ | `emptyMessage` | `string` | `'No matches'` | Message shown in the popover when the typed text matches no option. |
1798
+ | `className` | `string` | | Extra class names for the wrapper element, merged with the component's own classes. |
1799
+
1800
+ ### RudiToastRegion
1801
+
1802
+ Renders toasts queued with `rudiToast`. Mount exactly one, near the app
1803
+ root. It portals into `document.body` and renders nothing while the queue
1804
+ is empty. The region is an ARIA landmark (F6 moves focus into it) and each
1805
+ toast is announced to screen readers when it appears. Queue toasts with `rudiToast`, not
1806
+ through props.
1807
+
1808
+ ```tsx
1809
+ <RudiToastRegion placement="bottom-end" />
1810
+ ```
1811
+
1812
+ | Prop | Type | Default | Description |
1813
+ | --- | --- | --- | --- |
1814
+ | `placement` | `'top-end' \| 'bottom-end' \| 'bottom-center'` | `'bottom-end'` | Where the toasts stack: the top or bottom inline-end corner of the viewport, or bottom center. |
1815
+ | `aria-label` | `string` | | Accessible name for the notifications landmark. Defaults to a localized "Notifications" label. |
1816
+ | `closeLabel` | `string` | `'Close'` | Accessible label of every toast's close button. |
1817
+ | `className` | `string` | | Class merged onto the region element. |
1818
+
1819
+ ### RudiTable
1820
+
1821
+ Accessible data table built on React Aria Components' `Table`. Wraps the grid in a scroll
1822
+ container so wide tables scroll horizontally instead of overflowing the page. Needs an accessible
1823
+ name: pass `aria-label` or `aria-labelledby`. Selection, sorting and row actions come from React
1824
+ Aria (`selectionMode`, `sortDescriptor`, `onSortChange`, `onRowAction`). Compose with
1825
+ `RudiTableHeader`, `RudiTableColumn`, `RudiTableBody`, `RudiTableRow` and `RudiTableCell`.
1826
+
1827
+ ```tsx
1828
+ <RudiTable aria-label="Shipments" density="compact">
1829
+ <RudiTableHeader>
1830
+ <RudiTableColumn isRowHeader>Reference</RudiTableColumn>
1831
+ <RudiTableColumn align="end">Weight</RudiTableColumn>
1832
+ </RudiTableHeader>
1833
+ <RudiTableBody>
1834
+ <RudiTableRow id="1">
1835
+ <RudiTableCell>REF-1042</RudiTableCell>
1836
+ <RudiTableCell>12 kg</RudiTableCell>
1837
+ </RudiTableRow>
1838
+ </RudiTableBody>
1839
+ </RudiTable>
1840
+ ```
1841
+
1842
+ | Prop | Type | Default | Description |
1843
+ | --- | --- | --- | --- |
1844
+ | `aria-label` | `string` | | Accessible name for the table. Required unless `aria-labelledby` is set. Accessible name for the table. |
1845
+ | `aria-labelledby` | `string` | | Id of an element that names the table. Id of an element that names the table. Required unless `aria-label` is set. |
1846
+ | `density` | `'compact' \| 'regular'` | `'regular'` | Row height and cell padding. |
1847
+ | `striped` | `boolean` | `false` | Alternate row backgrounds (zebra striping). |
1848
+ | `stickyHeader` | `boolean` | `false` | Pin the header row while the body scrolls. The header sticks to the table's own scroll container, so pair it with `maxHeight`. |
1849
+ | `maxHeight` | `string \| number` | | Max height of the scroll container (CSS length or px number). Enables vertical scrolling. |
1850
+ | `className` | `string` | | Class merged onto the outer scroll container. |
1851
+
1852
+ Inherited from React Aria (types and descriptions in `components.json`): `children`, `aria-describedby`, `aria-details`, `escapeKeyBehavior`, `disabledKeys`, `selectionMode`, `disallowEmptySelection`, `selectedKeys`, `defaultSelectedKeys`, `onSelectionChange`, `shouldSelectOnPressUp`, `sortDescriptor`, `onSortChange`, `selectionBehavior`, `disabledBehavior`, `onRowAction`, `dragAndDropHooks`.
1853
+
1854
+ `ref` forwards to `HTMLTableElement`. Also accepts React Aria's global DOM props (`DOMRenderProps`, `GlobalDOMAttributes`, `GlobalDOMEvents`, `SlotProps`).
1855
+
1856
+ ### RudiTableHeader
1857
+
1858
+ The header row. Pass static `RudiTableColumn` children, or `columns` plus a render function.
1859
+ A selection column is prepended automatically when the table has a `selectionMode` and its `selectionBehavior` is `toggle` (the default).
1860
+
1861
+ ```tsx
1862
+ <RudiTableHeader>
1863
+ <RudiTableColumn isRowHeader>Name</RudiTableColumn>
1864
+ </RudiTableHeader>
1865
+ ```
1866
+
1867
+ | Prop | Type | Default | Description |
1868
+ | --- | --- | --- | --- |
1869
+ | `className` | `string` | | Class merged onto the header element. |
1870
+
1871
+ Inherited from React Aria (types and descriptions in `components.json`): `children`, `dependencies`, `onHoverStart`, `onHoverEnd`, `onHoverChange`, `columns`.
1872
+
1873
+ Also accepts React Aria's global DOM props (`DOMRenderProps`, `GlobalDOMAttributes`, `GlobalDOMEvents`).
1874
+
1875
+ ### RudiTableColumn
1876
+
1877
+ A column header in `RudiTableHeader`. Mark one column `isRowHeader` so screen readers can name
1878
+ each row. Set `allowsSorting` for a sortable column, which shows a sort icon, and handle sorting
1879
+ on the table with `sortDescriptor` and `onSortChange`.
1880
+
1881
+ ```tsx
1882
+ <RudiTableColumn id="weight" allowsSorting align="end" width={120}>Weight</RudiTableColumn>
1883
+ ```
1884
+
1885
+ | Prop | Type | Default | Description |
1886
+ | --- | --- | --- | --- |
1887
+ | `align` | `RudiTableAlign` | `'start'` | Horizontal alignment of the header and every cell in this column. Use `end` for numbers. |
1888
+ | `width` | `string \| number` | | Column width (CSS length or px number). |
1889
+ | `minWidth` | `string \| number` | | Minimum column width (CSS length or px number). |
1890
+ | `children` | `ReactNode` | | Header label. A plain string also becomes the `textValue` unless one is given. |
1891
+ | `className` | `string` | | Class merged onto the column header element. |
1892
+
1893
+ Inherited from React Aria (types and descriptions in `components.json`): `id`, `allowsSorting`, `isRowHeader`, `textValue`.
1894
+
1895
+ Also accepts React Aria's global DOM props (`DOMRenderProps`, `GlobalDOMAttributes`, `GlobalDOMEvents`).
1896
+
1897
+ ### RudiTableBody
1898
+
1899
+ The table body. Pass static `RudiTableRow` children, or `items` plus a render function.
1900
+ `renderEmptyState` renders (full width) when there are no rows — e.g. a `RudiEmptyState`.
1901
+
1902
+ ```tsx
1903
+ <RudiTableBody items={rows}>
1904
+ {(row) => <RudiTableRow><RudiTableCell>{row.name}</RudiTableCell></RudiTableRow>}
1905
+ </RudiTableBody>
1906
+ ```
1907
+
1908
+ | Prop | Type | Default | Description |
1909
+ | --- | --- | --- | --- |
1910
+ | `className` | `string` | | Class merged onto the body element. |
1911
+
1912
+ Inherited from React Aria (types and descriptions in `components.json`): `children`, `items`, `dependencies`, `renderEmptyState`.
1913
+
1914
+ Also accepts React Aria's global DOM props (`DOMRenderProps`, `GlobalDOMAttributes`, `GlobalDOMEvents`).
1915
+
1916
+ ### RudiTableRow
1917
+
1918
+ A table row. Give it `href` to make the whole row a link (routed through
1919
+ `RudiRouterProvider`), or handle `onAction` / the table's `onRowAction`. Give each row an `id`
1920
+ so selection and actions can refer to it. A selection checkbox cell is prepended automatically
1921
+ when the table has a `selectionMode` and its `selectionBehavior` is `toggle` (the default).
1922
+
1923
+ ```tsx
1924
+ <RudiTableRow id="1" href="/shipments/1">
1925
+ <RudiTableCell>REF-1042</RudiTableCell>
1926
+ </RudiTableRow>
1927
+ ```
1928
+
1929
+ | Prop | Type | Default | Description |
1930
+ | --- | --- | --- | --- |
1931
+ | `className` | `string` | | Class merged onto the row element. |
1932
+
1933
+ Inherited from React Aria (types and descriptions in `components.json`): `children`, `isDisabled`, `onPress`, `onPressStart`, `onPressEnd`, `onPressChange`, `onPressUp`, `onClick`, `href`, `target`, `rel`, `value`, `id`, `onAction`, `download`, `hrefLang`, `ping`, `referrerPolicy`, `dependencies`, `routerOptions`, `onHoverStart`, `onHoverEnd`, `onHoverChange`, `columns`, `textValue`.
1934
+
1935
+ Also accepts React Aria's global DOM props (`DOMRenderProps`, `GlobalDOMAttributes`, `GlobalDOMEvents`).
1936
+
1937
+ ### RudiTableCell
1938
+
1939
+ A data cell in a `RudiTableRow`, in the same order as the table's columns. It inherits its
1940
+ column's `align` unless it sets its own. Focusing a text field inside the cell pauses the grid's
1941
+ arrow-key navigation so the field keeps the keys.
1942
+
1943
+ ```tsx
1944
+ <RudiTableCell align="end">12 kg</RudiTableCell>
1945
+ ```
1946
+
1947
+ | Prop | Type | Default | Description |
1948
+ | --- | --- | --- | --- |
1949
+ | `align` | `RudiTableAlign` | | Overrides the alignment inherited from the cell's `RudiTableColumn`. |
1950
+ | `children` | `ReactNode` | | Cell content. A plain string also becomes the `textValue` unless one is given. |
1951
+ | `className` | `string` | | Class merged onto the cell element. |
1952
+
1953
+ Inherited from React Aria (types and descriptions in `components.json`): `id`, `colSpan`, `textValue`.
1954
+
1955
+ Also accepts React Aria's global DOM props (`DOMRenderProps`, `GlobalDOMAttributes`, `GlobalDOMEvents`).
1956
+
1957
+ ### RudiDatePicker
1958
+
1959
+ A date (or date and time) field with segmented keyboard entry and a calendar popover. Values are ISO strings: `YYYY-MM-DD`, or `YYYY-MM-DDTHH:mm` with `granularity="minute"`. `label` is required. Use `RudiDateRangePicker` for a start and end date. Ref points at the wrapper `div`.
1960
+
1961
+ ```tsx
1962
+ <RudiDatePicker label="Due date" value={due} onChange={setDue} />
1963
+ ```
1964
+
1965
+ | Prop | Type | Default | Description |
1966
+ | --- | --- | --- | --- |
1967
+ | `label` *(required)* | `string` | | Visible label and the field's accessible name. Required. |
1968
+ | `value` | `string \| null` | | Controlled value: `YYYY-MM-DD` for `granularity="day"`, or `YYYY-MM-DDTHH:mm` for `granularity="minute"`. `null` clears the field. |
1969
+ | `defaultValue` | `string \| null` | | Initial value for an uncontrolled field, in the same string format as `value`. Read only on mount. |
1970
+ | `onChange` | `(value: string \| null) => void` | | Receives the value in the same string format, or `null` when cleared or incomplete. |
1971
+ | `granularity` | `RudiDateGranularity` | `'day'` | `day` shows date segments; `minute` adds hour and minute segments. |
1972
+ | `minValue` | `string` | | Earliest selectable value, same string format as `value`. |
1973
+ | `maxValue` | `string` | | Latest selectable value, same string format as `value`. |
1974
+ | `isDateUnavailable` | `(date: string) => boolean` | | Return `true` to disable a `YYYY-MM-DD` date (weekends, holidays). |
1975
+ | `description` | `string` | | Help text under the field. Hidden while the field is invalid (an `errorMessage`, or a value outside `minValue`/`maxValue` or flagged by `isDateUnavailable`). |
1976
+ | `errorMessage` | `string` | | Shows the message and marks the field invalid. |
1977
+ | `isRequired` | `boolean` | `false` | Marks the field required and adds an asterisk to the label. |
1978
+ | `isDisabled` | `boolean` | `false` | Disables the field and the calendar button. |
1979
+ | `isReadOnly` | `boolean` | `false` | Makes the value focusable but not editable, and disables the calendar. |
1980
+ | `name` | `string` | | Form field name. Submits `YYYY-MM-DD`, or `YYYY-MM-DDTHH:mm:ss` with `granularity="minute"`. |
1981
+ | `hourCycle` | `12 \| 24` | | Force a 12- or 24-hour clock in minute granularity. Defaults to the locale. |
1982
+ | `className` | `string` | | Extra class names for the wrapper element, merged with the component's own classes. |
1983
+
1984
+ `ref` forwards to `HTMLDivElement`.
1985
+
1986
+ ### RudiDateRangePicker
1987
+
1988
+ A start and end date field with segmented keyboard entry and a range calendar popover. Values are `{ start, end }` objects of `YYYY-MM-DD` strings. `label` is required. Use `RudiDatePicker` for a single date. Day granularity only. Ref points at the wrapper `div`.
1989
+
1990
+ ```tsx
1991
+ <RudiDateRangePicker label="Stay" value={range} onChange={setRange} />
1992
+ ```
1993
+
1994
+ | Prop | Type | Default | Description |
1995
+ | --- | --- | --- | --- |
1996
+ | `label` *(required)* | `string` | | Visible label and the field's accessible name. Required. |
1997
+ | `value` | `RudiDateRange \| null` | | Controlled range of `YYYY-MM-DD` strings. `null` clears the field. |
1998
+ | `defaultValue` | `RudiDateRange \| null` | | Initial range for an uncontrolled field. Read only on mount. |
1999
+ | `onChange` | `(value: RudiDateRange \| null) => void` | | Receives `{ start, end }` once both ends are set, or `null` when cleared. |
2000
+ | `minValue` | `string` | | Earliest selectable date, `YYYY-MM-DD`. |
2001
+ | `maxValue` | `string` | | Latest selectable date, `YYYY-MM-DD`. |
2002
+ | `isDateUnavailable` | `(date: string) => boolean` | | Return `true` to disable a `YYYY-MM-DD` date. |
2003
+ | `description` | `string` | | Help text under the field. Hidden while the field is invalid (an `errorMessage`, or a value outside `minValue`/`maxValue` or flagged by `isDateUnavailable`). |
2004
+ | `errorMessage` | `string` | | Shows the message and marks the field invalid. |
2005
+ | `isRequired` | `boolean` | `false` | Marks the field required and adds an asterisk to the label. |
2006
+ | `isDisabled` | `boolean` | `false` | Disables the field and the calendar button. |
2007
+ | `isReadOnly` | `boolean` | `false` | Makes the value focusable but not editable, and disables the calendar. |
2008
+ | `startName` | `string` | | Form field name for the start date (submits `YYYY-MM-DD`). |
2009
+ | `endName` | `string` | | Form field name for the end date (submits `YYYY-MM-DD`). |
2010
+ | `className` | `string` | | Extra class names for the wrapper element, merged with the component's own classes. |
2011
+
2012
+ `ref` forwards to `HTMLDivElement`.
2013
+
2014
+ ### RudiNumberField
2015
+
2016
+ A numeric field with locale-aware parsing, optional currency or percent formatting, and stepper buttons. Use it instead of `RudiInput type="number"`. `label` is required. `onChange` receives a number, or `null` when cleared. Ref points at the `<input>`.
2017
+
2018
+ ```tsx
2019
+ <RudiNumberField label="Quantity" minValue={1} value={qty} onChange={setQty} />
2020
+ ```
2021
+
2022
+ | Prop | Type | Default | Description |
2023
+ | --- | --- | --- | --- |
2024
+ | `label` *(required)* | `string` | | Visible label and the field's accessible name. Required. |
2025
+ | `labelHidden` | `boolean` | `false` | Hides the label visually but keeps it as the accessible name. |
2026
+ | `value` | `number \| null` | | Controlled value. `null` renders an empty field. |
2027
+ | `defaultValue` | `number \| null` | | Initial value for an uncontrolled field. `null` starts empty. |
2028
+ | `onChange` | `(value: number \| null) => void` | | Receives the parsed number, or `null` when the field is cleared. |
2029
+ | `minValue` | `number` | | Smallest allowed value; the stepper and arrow keys stop here and typed values clamp to it. |
2030
+ | `maxValue` | `number` | | Largest allowed value; the stepper and arrow keys stop here and typed values clamp to it. |
2031
+ | `step` | `number` | | Increment for the stepper buttons and arrow keys; values snap to it. |
2032
+ | `formatOptions` | `Intl.NumberFormatOptions` | | Display format, e.g. `{ style: 'currency', currency: 'USD' }` or `{ style: 'percent' }`. Percent values are fractions (`0.25` shows `25%`). |
2033
+ | `placeholder` | `string` | | Hint text shown while the field is empty. Not a substitute for `label`. |
2034
+ | `description` | `string` | | Help text under the field. Hidden while `errorMessage` is shown. |
2035
+ | `errorMessage` | `string` | | Shows the message and marks the field invalid. |
2036
+ | `isRequired` | `boolean` | `false` | Marks the field required and adds an asterisk to the label. |
2037
+ | `isDisabled` | `boolean` | `false` | Disables the field and its stepper buttons. |
2038
+ | `isReadOnly` | `boolean` | `false` | Makes the value selectable and focusable but not editable. |
2039
+ | `name` | `string` | | Form field name; submits the raw number. |
2040
+ | `hideStepper` | `boolean` | `false` | Hides the minus and plus buttons; arrow keys still change the value. |
2041
+ | `className` | `string` | | Extra class names for the wrapper element, merged with the component's own classes. |
2042
+
2043
+ `ref` forwards to `HTMLInputElement`.
2044
+
2045
+ ## Functions and hooks
2046
+
2047
+ ### cn
2048
+
2049
+ Joins class names with `clsx` and resolves conflicting Tailwind utilities with `tailwind-merge`.
2050
+ Falsy values are dropped. Components use it so a consumer's `className` is merged, not replaced.
2051
+
2052
+ ```ts
2053
+ (...inputs: ClassValue[]) => string
2054
+ ```
2055
+
2056
+ ```tsx
2057
+ cn('rudi-button', isBusy && 'rudi-button--busy', className)
2058
+ ```
2059
+
2060
+ ### useLoadingButton
2061
+
2062
+ Button behavior with a loading state, for building custom buttons. Wraps React Aria's `useButton`,
2063
+ disables the button while `isLoading` (so it cannot be pressed twice) and sets `aria-busy`.
2064
+ Spread the returned `buttonProps` on a `<button>`; `RudiButton` uses this internally.
2065
+
2066
+ ```ts
2067
+ (ariaProps: AriaButtonProps, isLoading: boolean, ref: RefObject<HTMLButtonElement | null>) => { buttonProps: { 'aria-busy': true | undefined; disabled?: boolean | undefined; form?: string | undefined; formAction?: string | ((formData: FormData) => void | Promise<void>) | DO_NOT_USE_OR_YOU_WILL_BE_FIRED_EXPERIMENTAL_FORM_ACTIONS[keyof DO_NOT_USE_OR_YOU_WILL_BE_FIRED_EXPERIMENTAL_FORM_ACTIONS] | undefined; formEncType?: string | undefined; formMethod?: string | undefined; formNoValidate?: boolean | undefined; formTarget?: string | undefined; name?: string | undefined; type?: "submit" | "reset" | "button" | undefined; value?: string | readonly string[] | number | undefined; defaultChecked?: boolean | undefined; defaultValue?: string | number | readonly string[] | undefined; suppressContentEditableWarning?: boolean | undefined; suppressHydrationWarning?: boolean | undefined; accessKey?: string | undefined; autoCapitalize?: "off" | "none" | "on" | "sentences" | "words" | "characters" | undefined | (string & {}); autoFocus?: boolean | undefined; className?: string | undefined; contentEditable?: Booleanish | "inherit" | "plaintext-only" | undefined; contextMenu?: string | undefined; dir?: string | undefined; draggable?: Booleanish | undefined; enterKeyHint?: "enter" | "done" | "go" | "next" | "previous" | "search" | "send" | undefined; hidden?: boolean | undefined; id?: string | undefined; lang?: string | undefined; nonce?: string | undefined; slot?: string | undefined; spellCheck?: Booleanish | undefined; style?: CSSProperties | undefined; tabIndex?: number | undefined; title?: string | undefined; translate?: "yes" | "no" | undefined; radioGroup?: string | undefined; role?: AriaRole | undefined; about?: string | undefined; content?: string | undefined; datatype?: string | undefined; inlist?: any; prefix?: string | undefined; property?: string | undefined; rel?: string | undefined; resource?: string | undefined; rev?: string | undefined; typeof?: string | undefined; vocab?: string | undefined; autoCorrect?: string | undefined; autoSave?: string | undefined; color?: string | undefined; itemProp?: string | undefined; itemScope?: boolean | undefined; itemType?: string | undefined; itemID?: string | undefined; itemRef?: string | undefined; results?: number | undefined; security?: string | undefined; unselectable?: "on" | "off" | undefined; popover?: "" | "auto" | "manual" | "hint" | undefined; popoverTargetAction?: "toggle" | "show" | "hide" | undefined; popoverTarget?: string | undefined; inert?: boolean | undefined; inputMode?: "none" | "text" | "tel" | "url" | "email" | "numeric" | "decimal" | "search" | undefined; is?: string | undefined; exportparts?: string | undefined; part?: string | undefined; "aria-activedescendant"?: string | undefined; "aria-atomic"?: Booleanish | undefined; "aria-autocomplete"?: "none" | "inline" | "list" | "both" | undefined; "aria-braillelabel"?: string | undefined; "aria-brailleroledescription"?: string | undefined; "aria-checked"?: boolean | "false" | "mixed" | "true" | undefined; "aria-colcount"?: number | undefined; "aria-colindex"?: number | undefined; "aria-colindextext"?: string | undefined; "aria-colspan"?: number | undefined; "aria-controls"?: string | undefined; "aria-current"?: boolean | "false" | "true" | "page" | "step" | "location" | "date" | "time" | undefined; "aria-describedby"?: string | undefined; "aria-description"?: string | undefined; "aria-details"?: string | undefined; "aria-disabled"?: Booleanish | undefined; "aria-dropeffect"?: "none" | "copy" | "execute" | "link" | "move" | "popup" | undefined; "aria-errormessage"?: string | undefined; "aria-expanded"?: Booleanish | undefined; "aria-flowto"?: string | undefined; "aria-grabbed"?: Booleanish | undefined; "aria-haspopup"?: boolean | "false" | "true" | "menu" | "listbox" | "tree" | "grid" | "dialog" | undefined; "aria-hidden"?: Booleanish | undefined; "aria-invalid"?: boolean | "false" | "true" | "grammar" | "spelling" | undefined; "aria-keyshortcuts"?: string | undefined; "aria-label"?: string | undefined; "aria-labelledby"?: string | undefined; "aria-level"?: number | undefined; "aria-live"?: "off" | "assertive" | "polite" | undefined; "aria-modal"?: Booleanish | undefined; "aria-multiline"?: Booleanish | undefined; "aria-multiselectable"?: Booleanish | undefined; "aria-orientation"?: "horizontal" | "vertical" | undefined; "aria-owns"?: string | undefined; "aria-placeholder"?: string | undefined; "aria-posinset"?: number | undefined; "aria-pressed"?: boolean | "false" | "mixed" | "true" | undefined; "aria-readonly"?: Booleanish | undefined; "aria-relevant"?: "additions" | "additions removals" | "additions text" | "all" | "removals" | "removals additions" | "removals text" | "text" | "text additions" | "text removals" | undefined; "aria-required"?: Booleanish | undefined; "aria-roledescription"?: string | undefined; "aria-rowcount"?: number | undefined; "aria-rowindex"?: number | undefined; "aria-rowindextext"?: string | undefined; "aria-rowspan"?: number | undefined; "aria-selected"?: Booleanish | undefined; "aria-setsize"?: number | undefined; "aria-sort"?: "none" | "ascending" | "descending" | "other" | undefined; "aria-valuemax"?: number | undefined; "aria-valuemin"?: number | undefined; "aria-valuenow"?: number | undefined; "aria-valuetext"?: string | undefined; children?: ReactNode | undefined; dangerouslySetInnerHTML?: { __html: string | TrustedHTML; } | undefined; onCopy?: ClipboardEventHandler<HTMLButtonElement> | undefined; onCopyCapture?: ClipboardEventHandler<HTMLButtonElement> | undefined; onCut?: ClipboardEventHandler<HTMLButtonElement> | undefined; onCutCapture?: ClipboardEventHandler<HTMLButtonElement> | undefined; onPaste?: ClipboardEventHandler<HTMLButtonElement> | undefined; onPasteCapture?: ClipboardEventHandler<HTMLButtonElement> | undefined; onCompositionEnd?: CompositionEventHandler<HTMLButtonElement> | undefined; onCompositionEndCapture?: CompositionEventHandler<HTMLButtonElement> | undefined; onCompositionStart?: CompositionEventHandler<HTMLButtonElement> | undefined; onCompositionStartCapture?: CompositionEventHandler<HTMLButtonElement> | undefined; onCompositionUpdate?: CompositionEventHandler<HTMLButtonElement> | undefined; onCompositionUpdateCapture?: CompositionEventHandler<HTMLButtonElement> | undefined; onFocus?: FocusEventHandler<HTMLButtonElement> | undefined; onFocusCapture?: FocusEventHandler<HTMLButtonElement> | undefined; onBlur?: FocusEventHandler<HTMLButtonElement> | undefined; onBlurCapture?: FocusEventHandler<HTMLButtonElement> | undefined; onChange?: ChangeEventHandler<HTMLButtonElement, Element> | undefined; onChangeCapture?: ChangeEventHandler<HTMLButtonElement, Element> | undefined; onBeforeInput?: InputEventHandler<HTMLButtonElement> | undefined; onBeforeInputCapture?: InputEventHandler<HTMLButtonElement> | undefined; onInput?: InputEventHandler<HTMLButtonElement> | undefined; onInputCapture?: InputEventHandler<HTMLButtonElement> | undefined; onReset?: ReactEventHandler<HTMLButtonElement> | undefined; onResetCapture?: ReactEventHandler<HTMLButtonElement> | undefined; onSubmit?: SubmitEventHandler<HTMLButtonElement> | undefined; onSubmitCapture?: SubmitEventHandler<HTMLButtonElement> | undefined; onInvalid?: ReactEventHandler<HTMLButtonElement> | undefined; onInvalidCapture?: ReactEventHandler<HTMLButtonElement> | undefined; onLoad?: ReactEventHandler<HTMLButtonElement> | undefined; onLoadCapture?: ReactEventHandler<HTMLButtonElement> | undefined; onError?: ReactEventHandler<HTMLButtonElement> | undefined; onErrorCapture?: ReactEventHandler<HTMLButtonElement> | undefined; onKeyDown?: KeyboardEventHandler<HTMLButtonElement> | undefined; onKeyDownCapture?: KeyboardEventHandler<HTMLButtonElement> | undefined; onKeyPress?: KeyboardEventHandler<HTMLButtonElement> | undefined; onKeyPressCapture?: KeyboardEventHandler<HTMLButtonElement> | undefined; onKeyUp?: KeyboardEventHandler<HTMLButtonElement> | undefined; onKeyUpCapture?: KeyboardEventHandler<HTMLButtonElement> | undefined; onAbort?: ReactEventHandler<HTMLButtonElement> | undefined; onAbortCapture?: ReactEventHandler<HTMLButtonElement> | undefined; onCanPlay?: ReactEventHandler<HTMLButtonElement> | undefined; onCanPlayCapture?: ReactEventHandler<HTMLButtonElement> | undefined; onCanPlayThrough?: ReactEventHandler<HTMLButtonElement> | undefined; onCanPlayThroughCapture?: ReactEventHandler<HTMLButtonElement> | undefined; onDurationChange?: ReactEventHandler<HTMLButtonElement> | undefined; onDurationChangeCapture?: ReactEventHandler<HTMLButtonElement> | undefined; onEmptied?: ReactEventHandler<HTMLButtonElement> | undefined; onEmptiedCapture?: ReactEventHandler<HTMLButtonElement> | undefined; onEncrypted?: ReactEventHandler<HTMLButtonElement> | undefined; onEncryptedCapture?: ReactEventHandler<HTMLButtonElement> | undefined; onEnded?: ReactEventHandler<HTMLButtonElement> | undefined; onEndedCapture?: ReactEventHandler<HTMLButtonElement> | undefined; onLoadedData?: ReactEventHandler<HTMLButtonElement> | undefined; onLoadedDataCapture?: ReactEventHandler<HTMLButtonElement> | undefined; onLoadedMetadata?: ReactEventHandler<HTMLButtonElement> | undefined; onLoadedMetadataCapture?: ReactEventHandler<HTMLButtonElement> | undefined; onLoadStart?: ReactEventHandler<HTMLButtonElement> | undefined; onLoadStartCapture?: ReactEventHandler<HTMLButtonElement> | undefined; onPause?: ReactEventHandler<HTMLButtonElement> | undefined; onPauseCapture?: ReactEventHandler<HTMLButtonElement> | undefined; onPlay?: ReactEventHandler<HTMLButtonElement> | undefined; onPlayCapture?: ReactEventHandler<HTMLButtonElement> | undefined; onPlaying?: ReactEventHandler<HTMLButtonElement> | undefined; onPlayingCapture?: ReactEventHandler<HTMLButtonElement> | undefined; onProgress?: ReactEventHandler<HTMLButtonElement> | undefined; onProgressCapture?: ReactEventHandler<HTMLButtonElement> | undefined; onRateChange?: ReactEventHandler<HTMLButtonElement> | undefined; onRateChangeCapture?: ReactEventHandler<HTMLButtonElement> | undefined; onSeeked?: ReactEventHandler<HTMLButtonElement> | undefined; onSeekedCapture?: ReactEventHandler<HTMLButtonElement> | undefined; onSeeking?: ReactEventHandler<HTMLButtonElement> | undefined; onSeekingCapture?: ReactEventHandler<HTMLButtonElement> | undefined; onStalled?: ReactEventHandler<HTMLButtonElement> | undefined; onStalledCapture?: ReactEventHandler<HTMLButtonElement> | undefined; onSuspend?: ReactEventHandler<HTMLButtonElement> | undefined; onSuspendCapture?: ReactEventHandler<HTMLButtonElement> | undefined; onTimeUpdate?: ReactEventHandler<HTMLButtonElement> | undefined; onTimeUpdateCapture?: ReactEventHandler<HTMLButtonElement> | undefined; onVolumeChange?: ReactEventHandler<HTMLButtonElement> | undefined; onVolumeChangeCapture?: ReactEventHandler<HTMLButtonElement> | undefined; onWaiting?: ReactEventHandler<HTMLButtonElement> | undefined; onWaitingCapture?: ReactEventHandler<HTMLButtonElement> | undefined; onAuxClick?: MouseEventHandler<HTMLButtonElement> | undefined; onAuxClickCapture?: MouseEventHandler<HTMLButtonElement> | undefined; onClick?: MouseEventHandler<HTMLButtonElement> | undefined; onClickCapture?: MouseEventHandler<HTMLButtonElement> | undefined; onContextMenu?: MouseEventHandler<HTMLButtonElement> | undefined; onContextMenuCapture?: MouseEventHandler<HTMLButtonElement> | undefined; onDoubleClick?: MouseEventHandler<HTMLButtonElement> | undefined; onDoubleClickCapture?: MouseEventHandler<HTMLButtonElement> | undefined; onDrag?: DragEventHandler<HTMLButtonElement> | undefined; onDragCapture?: DragEventHandler<HTMLButtonElement> | undefined; onDragEnd?: DragEventHandler<HTMLButtonElement> | undefined; onDragEndCapture?: DragEventHandler<HTMLButtonElement> | undefined; onDragEnter?: DragEventHandler<HTMLButtonElement> | undefined; onDragEnterCapture?: DragEventHandler<HTMLButtonElement> | undefined; onDragExit?: DragEventHandler<HTMLButtonElement> | undefined; onDragExitCapture?: DragEventHandler<HTMLButtonElement> | undefined; onDragLeave?: DragEventHandler<HTMLButtonElement> | undefined; onDragLeaveCapture?: DragEventHandler<HTMLButtonElement> | undefined; onDragOver?: DragEventHandler<HTMLButtonElement> | undefined; onDragOverCapture?: DragEventHandler<HTMLButtonElement> | undefined; onDragStart?: DragEventHandler<HTMLButtonElement> | undefined; onDragStartCapture?: DragEventHandler<HTMLButtonElement> | undefined; onDrop?: DragEventHandler<HTMLButtonElement> | undefined; onDropCapture?: DragEventHandler<HTMLButtonElement> | undefined; onMouseDown?: MouseEventHandler<HTMLButtonElement> | undefined; onMouseDownCapture?: MouseEventHandler<HTMLButtonElement> | undefined; onMouseEnter?: MouseEventHandler<HTMLButtonElement> | undefined; onMouseLeave?: MouseEventHandler<HTMLButtonElement> | undefined; onMouseMove?: MouseEventHandler<HTMLButtonElement> | undefined; onMouseMoveCapture?: MouseEventHandler<HTMLButtonElement> | undefined; onMouseOut?: MouseEventHandler<HTMLButtonElement> | undefined; onMouseOutCapture?: MouseEventHandler<HTMLButtonElement> | undefined; onMouseOver?: MouseEventHandler<HTMLButtonElement> | undefined; onMouseOverCapture?: MouseEventHandler<HTMLButtonElement> | undefined; onMouseUp?: MouseEventHandler<HTMLButtonElement> | undefined; onMouseUpCapture?: MouseEventHandler<HTMLButtonElement> | undefined; onSelect?: ReactEventHandler<HTMLButtonElement> | undefined; onSelectCapture?: ReactEventHandler<HTMLButtonElement> | undefined; onTouchCancel?: TouchEventHandler<HTMLButtonElement> | undefined; onTouchCancelCapture?: TouchEventHandler<HTMLButtonElement> | undefined; onTouchEnd?: TouchEventHandler<HTMLButtonElement> | undefined; onTouchEndCapture?: TouchEventHandler<HTMLButtonElement> | undefined; onTouchMove?: TouchEventHandler<HTMLButtonElement> | undefined; onTouchMoveCapture?: TouchEventHandler<HTMLButtonElement> | undefined; onTouchStart?: TouchEventHandler<HTMLButtonElement> | undefined; onTouchStartCapture?: TouchEventHandler<HTMLButtonElement> | undefined; onPointerDown?: PointerEventHandler<HTMLButtonElement> | undefined; onPointerDownCapture?: PointerEventHandler<HTMLButtonElement> | undefined; onPointerMove?: PointerEventHandler<HTMLButtonElement> | undefined; onPointerMoveCapture?: PointerEventHandler<HTMLButtonElement> | undefined; onPointerUp?: PointerEventHandler<HTMLButtonElement> | undefined; onPointerUpCapture?: PointerEventHandler<HTMLButtonElement> | undefined; onPointerCancel?: PointerEventHandler<HTMLButtonElement> | undefined; onPointerCancelCapture?: PointerEventHandler<HTMLButtonElement> | undefined; onPointerEnter?: PointerEventHandler<HTMLButtonElement> | undefined; onPointerLeave?: PointerEventHandler<HTMLButtonElement> | undefined; onPointerOver?: PointerEventHandler<HTMLButtonElement> | undefined; onPointerOverCapture?: PointerEventHandler<HTMLButtonElement> | undefined; onPointerOut?: PointerEventHandler<HTMLButtonElement> | undefined; onPointerOutCapture?: PointerEventHandler<HTMLButtonElement> | undefined; onGotPointerCapture?: PointerEventHandler<HTMLButtonElement> | undefined; onGotPointerCaptureCapture?: PointerEventHandler<HTMLButtonElement> | undefined; onLostPointerCapture?: PointerEventHandler<HTMLButtonElement> | undefined; onLostPointerCaptureCapture?: PointerEventHandler<HTMLButtonElement> | undefined; onScroll?: UIEventHandler<HTMLButtonElement> | undefined; onScrollCapture?: UIEventHandler<HTMLButtonElement> | undefined; onScrollEnd?: UIEventHandler<HTMLButtonElement> | undefined; onScrollEndCapture?: UIEventHandler<HTMLButtonElement> | undefined; onWheel?: WheelEventHandler<HTMLButtonElement> | undefined; onWheelCapture?: WheelEventHandler<HTMLButtonElement> | undefined; onAnimationStart?: AnimationEventHandler<HTMLButtonElement> | undefined; onAnimationStartCapture?: AnimationEventHandler<HTMLButtonElement> | undefined; onAnimationEnd?: AnimationEventHandler<HTMLButtonElement> | undefined; onAnimationEndCapture?: AnimationEventHandler<HTMLButtonElement> | undefined; onAnimationIteration?: AnimationEventHandler<HTMLButtonElement> | undefined; onAnimationIterationCapture?: AnimationEventHandler<HTMLButtonElement> | undefined; onToggle?: ToggleEventHandler<HTMLButtonElement> | undefined; onBeforeToggle?: ToggleEventHandler<HTMLButtonElement> | undefined; onTransitionCancel?: TransitionEventHandler<HTMLButtonElement> | undefined; onTransitionCancelCapture?: TransitionEventHandler<HTMLButtonElement> | undefined; onTransitionEnd?: TransitionEventHandler<HTMLButtonElement> | undefined; onTransitionEndCapture?: TransitionEventHandler<HTMLButtonElement> | undefined; onTransitionRun?: TransitionEventHandler<HTMLButtonElement> | undefined; onTransitionRunCapture?: TransitionEventHandler<HTMLButtonElement> | undefined; onTransitionStart?: TransitionEventHandler<HTMLButtonElement> | undefined; onTransitionStartCapture?: TransitionEventHandler<HTMLButtonElement> | undefined; }; }
2068
+ ```
2069
+
2070
+ ```tsx
2071
+ const ref = useRef<HTMLButtonElement>(null)
2072
+ const { buttonProps } = useLoadingButton({ onPress: save }, isSaving, ref)
2073
+ return <button {...buttonProps} ref={ref}>Save</button>
2074
+ ```
2075
+
2076
+ ### useChartTheme
2077
+
2078
+ Reads the active theme's chart colors (series, axes, grid, tooltip and feedback tones) from the
2079
+ `--rudi-*` CSS custom properties, for chart libraries that need color values in JS. Re-resolves
2080
+ when `data-theme` on `<html>` changes or the OS color scheme flips. Returns light fallback
2081
+ colors on the server. Only the `data-theme` attribute on the document element is observed.
2082
+
2083
+ ```ts
2084
+ () => ChartTheme
2085
+ ```
2086
+
2087
+ ```tsx
2088
+ const theme = useChartTheme()
2089
+ <Line dataKey="value" stroke={theme.colors[0]} />
2090
+ ```
2091
+
2092
+ ### rudiToast
2093
+
2094
+ Show toasts from anywhere: `rudiToast.success('Saved')`. Requires one
2095
+ `RudiToastRegion` mounted near the app root. Every method returns the
2096
+ toast's key, which `rudiToast.close(key)` accepts. Success, info and warning toasts dismiss
2097
+ after 5000 ms by default; error toasts stay until closed.
2098
+
2099
+ ```ts
2100
+ { add: ({ title, description, variant, timeout, onClose }: RudiToastAddOptions) => string; success: (title: string, options?: RudiToastOptions) => string; info: (title: string, options?: RudiToastOptions) => string; warning: (title: string, options?: RudiToastOptions) => string; error: (title: string, options?: RudiToastOptions) => string; close: (key: string) => void; clear: () => void; }
2101
+ ```
2102
+
2103
+ ```tsx
2104
+ const key = rudiToast.error('Upload failed', { description: 'Try again.' })
2105
+ rudiToast.close(key)
2106
+ ```
2107
+
2108
+ ## Supporting types
2109
+
2110
+ ### RudiProgressBarVariant
2111
+
2112
+ Semantic color of the progress fill.
2113
+
2114
+ ```ts
2115
+ type RudiProgressBarVariant = "default" | "success" | "warning" | "error"
2116
+ ```
2117
+
2118
+ ### RudiProgressBarThreshold
2119
+
2120
+ Switches the fill color once progress reaches a percentage.
2121
+
2122
+ | Prop | Type | Default | Description |
2123
+ | --- | --- | --- | --- |
2124
+ | `at` *(required)* | `number` | | Minimum percentage (0–100) at which this variant takes effect. |
2125
+ | `variant` *(required)* | `RudiProgressBarVariant` | | Fill variant used once `at` is reached. |
2126
+
2127
+ ### RudiStepperStep
2128
+
2129
+ One step in a `RudiStepper`.
2130
+
2131
+ | Prop | Type | Default | Description |
2132
+ | --- | --- | --- | --- |
2133
+ | `label` *(required)* | `string` | | Step title. |
2134
+ | `description` | `string` | | Secondary text shown under the label. |
2135
+ | `icon` | `string` | | Iconify icon name for the node. Falls back to a check (complete) or the step number. |
2136
+ | `status` | `RudiStepStatus` | `'upcoming'` | Progress state of the step. |
2137
+
2138
+ ### RudiStepStatus
2139
+
2140
+ Progress state of a step: finished, in progress, or not yet reached.
2141
+
2142
+ ```ts
2143
+ type RudiStepStatus = "complete" | "current" | "upcoming"
2144
+ ```
2145
+
2146
+ ### RudiBreadcrumbItem
2147
+
2148
+ One entry in a `RudiBreadcrumb` trail.
2149
+
2150
+ | Prop | Type | Default | Description |
2151
+ | --- | --- | --- | --- |
2152
+ | `label` *(required)* | `string` | | Text shown for the crumb. |
2153
+ | `href` | `string` | | Link target. Without it the crumb renders as plain text. |
2154
+
2155
+ ### RudiChartReferenceLine
2156
+
2157
+ A horizontal guide line drawn across a `RudiLineChart`.
2158
+
2159
+ | Prop | Type | Default | Description |
2160
+ | --- | --- | --- | --- |
2161
+ | `y` *(required)* | `number` | | Value on the y axis where the line is drawn. |
2162
+ | `label` *(required)* | `string` | | Text shown on the line, at its top inline-end. |
2163
+ | `tone` | `'default' \| 'success' \| 'warning' \| 'error' \| 'info'` | `'default'` | Semantic color of the line and its label. |
2164
+
2165
+ ### RudiDonutChartDatum
2166
+
2167
+ One slice of a `RudiDonutChart`.
2168
+
2169
+ | Prop | Type | Default | Description |
2170
+ | --- | --- | --- | --- |
2171
+ | `name` *(required)* | `string` | | Slice name, used in the legend, tooltip, and slice labels. |
2172
+ | `value` *(required)* | `number` | | Size of the slice, relative to the sum of all values. |
2173
+
2174
+ ### RudiKanbanColumnData
2175
+
2176
+ Data for one board column.
2177
+
2178
+ | Prop | Type | Default | Description |
2179
+ | --- | --- | --- | --- |
2180
+ | `id` *(required)* | `string` | | Unique column id. Reported as `fromColumnId` / `toColumnId` in move events. |
2181
+ | `title` *(required)* | `string` | | Column heading. Also the column region's accessible name and used in drag announcements. |
2182
+ | `items` *(required)* | `RudiKanbanItem[]` | | Cards in display order. |
2183
+
2184
+ ### RudiKanbanItem
2185
+
2186
+ A card's data. Any extra fields are passed through to `renderCard`.
2187
+
2188
+ | Prop | Type | Default | Description |
2189
+ | --- | --- | --- | --- |
2190
+ | `id` *(required)* | `string` | | Unique across the whole board, not just its column. Used as the drag id. |
2191
+
2192
+ ### RudiKanbanCardMoveEvent
2193
+
2194
+ Describes a completed card drag. Use it to update your own column state.
2195
+
2196
+ | Prop | Type | Default | Description |
2197
+ | --- | --- | --- | --- |
2198
+ | `cardId` *(required)* | `string` | | `id` of the card that moved. |
2199
+ | `fromColumnId` *(required)* | `string` | | `id` of the column the card started in. |
2200
+ | `toColumnId` *(required)* | `string` | | `id` of the column the card was dropped in. |
2201
+ | `fromIndex` *(required)* | `number` | | Index of the card in its source column before the move. |
2202
+ | `toIndex` *(required)* | `number` | | The card's index in the destination column after the move, counted with the card removed from its source (so `items.splice(fromIndex, 1)` then `splice(toIndex, 0, card)` applies it). |
2203
+
2204
+ ### RudiTypographyWeight
2205
+
2206
+ Font weight options shared by `RudiText` and `RudiHeading`, mapped to the font-weight tokens.
2207
+
2208
+ ```ts
2209
+ type RudiTypographyWeight = "regular" | "medium" | "semibold" | "bold"
2210
+ ```
2211
+
2212
+ ### RudiTypographyTone
2213
+
2214
+ Semantic text colors shared by `RudiText` and `RudiHeading`, mapped to semantic color tokens that adapt per theme.
2215
+
2216
+ ```ts
2217
+ type RudiTypographyTone = "default" | "success" | "warning" | "error" | "subtle" | "disabled" | "brand" | "inverted" | "info"
2218
+ ```
2219
+
2220
+ ### RudiTypographyAlign
2221
+
2222
+ Text alignment options shared by `RudiText` and `RudiHeading`; `start` and `end` follow the writing direction.
2223
+
2224
+ ```ts
2225
+ type RudiTypographyAlign = "start" | "center" | "end" | "justify"
2226
+ ```
2227
+
2228
+ ### RudiDescriptionListItem
2229
+
2230
+ One term and description pair in a `RudiDescriptionList`.
2231
+
2232
+ | Prop | Type | Default | Description |
2233
+ | --- | --- | --- | --- |
2234
+ | `term` *(required)* | `React.ReactNode` | | The label, rendered in a `dt`. |
2235
+ | `description` *(required)* | `React.ReactNode` | | The value, rendered in a `dd`. |
2236
+ | `id` | `string` | | Stable key for the row; also set as the DOM `id` of the row wrapper. Falls back to the index for the key. |
2237
+
2238
+ ### RudiToastVariant
2239
+
2240
+ Severity of a toast. Sets its icon and colors, and its default timeout (`error` stays until closed).
2241
+
2242
+ ```ts
2243
+ type RudiToastVariant = "success" | "warning" | "error" | "info"
2244
+ ```
2245
+
2246
+ ### RudiToastOptions
2247
+
2248
+ Options accepted by `rudiToast.success`, `info`, `warning` and `error`.
2249
+
2250
+ | Prop | Type | Default | Description |
2251
+ | --- | --- | --- | --- |
2252
+ | `description` | `string` | | Supporting text shown under the title. |
2253
+ | `timeout` | `number` | | Auto-dismiss delay in ms. Omit for the variant default; pass `0` to keep the toast until closed. |
2254
+ | `onClose` | `() => void` | | Called when the toast closes, by the user or by timeout. |
2255
+
2256
+ ### RudiToastAddOptions
2257
+
2258
+ Options for `rudiToast.add`: the shared options plus the title and variant.
2259
+
2260
+ | Prop | Type | Default | Description |
2261
+ | --- | --- | --- | --- |
2262
+ | `title` *(required)* | `string` | | Main message shown in bold. |
2263
+ | `variant` *(required)* | `RudiToastVariant` | | Severity of the toast; sets icon, colors and the default timeout. |
2264
+ | `description` | `string` | | Supporting text shown under the title. |
2265
+ | `timeout` | `number` | | Auto-dismiss delay in ms. Omit for the variant default; pass `0` to keep the toast until closed. |
2266
+ | `onClose` | `() => void` | | Called when the toast closes, by the user or by timeout. |
2267
+
2268
+ ### RudiTableAlign
2269
+
2270
+ Horizontal alignment of table content: `start`, `center` or `end` (use `end` for numbers).
2271
+
2272
+ ```ts
2273
+ type RudiTableAlign = "start" | "center" | "end"
2274
+ ```
2275
+
2276
+ ### RudiDateRange
2277
+
2278
+ A date range as `YYYY-MM-DD` strings, passed to and from `RudiDateRangePicker`.
2279
+
2280
+ | Prop | Type | Default | Description |
2281
+ | --- | --- | --- | --- |
2282
+ | `start` *(required)* | `string` | | First day of the range, `YYYY-MM-DD`. |
2283
+ | `end` *(required)* | `string` | | Last day of the range, `YYYY-MM-DD`. |
2284
+