Ouro HXDocs
Components
Every Ouro HX component, with a live demo, install commands, its props and what to use instead. The same docs live in each component's JSDoc, so an agent reading the installed source sees them too.
Actions
- ButtonA button, or a link styled as one.
- ToggleA button that stays pressed until it is pressed again, such as Bold in a text toolbar.
- ToggleGroupA row of related toggles that share one value, such as text alignment or bold, italic and underline in a toolbar.
- ButtonGroupRelated buttons joined into one control, such as Previous, a page number and Next, or a split button.
- ColorSchemeToggleThe control that switches the app between light, dark and the system's scheme, and keeps the choice.
- CopyButtonA button that puts a piece of text on the clipboard: an API key, a link, a command.
- ShareButtonA button that shares a link: through the system's share sheet where there is one (phones, Safari), and by copying it where there is not, when it says "Link copied" for two seconds and screen readers hear it once.
Text
- TextBody text in the theme's type scale and colors.
- HeadingA section title,
<h1>to<h6>, in the theme's foreground color. - LinkA text link that navigates through your router.
- KbdA keyboard shortcut, in the reader's platform's notation:
keys={["mod", "k"]}shows ⌘K on a Mac, iPhone or iPad and Ctrl+K elsewhere. - LocalDateA date (and time) in the reader's own time zone and language, in a
<time>that carries the exact instant. - RelativeTimeHow long ago (or how soon) something happens, in the reader's language: "3 days ago", "yesterday", "in 5 minutes", "now", kept current while it shows.
Forms
- FieldA labeled form control: the label, an optional description, the control and its error, wired together with ids that match between the server and the browser.
- FieldsetA titled group of related fields, such as an address, rendered as a
<fieldset>named by its legend. - TextFieldA labeled one-line text input on the Field contract: pass
label, anderrorfrom your server action or client check. - TextAreaA labeled multi-line text field on the Field contract, a native
<textarea>: passlabel, anderrorfrom your server action or client check. - CheckboxA labeled checkbox on the Field contract, with the label to its right: pass
label, andcheckedwithonCheckedChange(ordefaultChecked). - CheckboxGroupA group of checkboxes under one legend, on the Field contract, for picking any number of choices: pass
legend, andoptions(orCheckboxchildren). - RadioGroupA group of radios under one legend, on the Field contract, for picking exactly one choice: pass
legend, andoptions(orRadiochildren). - SwitchA labeled on/off switch on the Field contract, with the label to its right: pass
label, andcheckedwithonCheckedChange(ordefaultChecked). - FormA form that validates with the browser's own constraints (
required,type="email",pattern) and shows server errors on the matching fields. - SelectA labeled list of choices on the Field contract: pass
label,options(orSelectItemchildren) anderrorfrom your server action or client check. - NativeSelectA labeled native
<select>on the Field contract: passlabel,options(or<option>children) anderror. - NumberFieldA labeled number input on the Field contract: pass
label, anderrorfrom your server action or client check. - SliderA labeled slider on the Field contract: pass
label, and adefaultValue(orvaluewithonValueChange). - ComboboxA text input that filters a list of items as people type, on the Field contract: pass
label,items, anderrorfrom your server action or client check. - OtpFieldA one-time code entry on the Field contract: one slot per character, with focus that moves as the person types, a whole code pasted at once, and
autoComplete="one-time-code"so phones offer the code from a text message. - FileFieldA labeled file input with a drop zone, on the Field contract.
- ColorFieldA color on the Field contract: a swatch that opens the system color picker, next to the same color as hex text, kept in step both ways.
- CalendarA month grid to pick a day or a range of days, with the arrow keys or a press.
- DatePickerA labeled date field.
- ChoiceCardA set of choices shown as cards, each with a picture, a label and a line of description, for picking exactly one: a cover photo, a plan, a layout.
- ImageCropperA dialog for cropping a photo to a shape before it is used: drag the photo (or move it the way the arrow keys point) to choose what shows in the frame, zoom with the slider (or Plus and Minus), and Save hands the cropped image to
onCropas aFile, ready for a form or an upload. - ImageFieldA field for one photo, shown large: the photo already saved (
src) or the one just chosen, with Choose photo (Change photo once one shows) and Remove.
Overlays
- SheetA panel that slides in from an edge and is dragged back to dismiss: the mobile form of a dialog.
- DialogA dialog that presents itself for the screen: a centered dialog on wider screens and a bottom sheet you can drag away on phones (below 640px).
- ConfirmDialogAsks the user to confirm an action, with Cancel focused first.
- EditSheetEdits something in a form inside a dialog: the whole interaction, done right.
- PopoverA small non-modal panel beside its trigger, for a short form or a few choices: a share link, filters, a quick edit.
- TooltipA short label that appears beside its trigger on hover and keyboard focus, for an icon button's purpose or a control's shortcut.
- HoverCardA preview of where a link goes, shown when a mouse rests on the link or the keyboard focuses it: a cook's profile, a recipe's summary.
Menus
Feedback
- ToasterShows the toasts you send with
toast("Saved")from@/lib/ouro/toast: render it once, at the root of your app, insideOuroProviderif you use one, or alone. - SpinnerA spinning ring that says something is loading.
- ProgressA bar that shows how far along a task is, or that it is under way when you can't tell.
- RouteProgressThe thin bar across the top of the screen while the app loads the next page or submits a form, so a click that waits on the server never feels frozen: one global affordance instead of a pending state on every action.
- TimerA countdown timer with its own controls: the time left in large numbers, Start, then Pause and Cancel, Resume when paused, and at zero "Time's up" with Dismiss and Restart.
- TimerTrayThe timers that are running, paused or finished, in one strip, so a person who leaves a timer's screen can still see it count down, hear it at zero, and stop it.
- CelebrateA small moment of celebration for something the person finished: confetti bursts from a badge with the message ("List cleared") and screen readers hear the message once.
- SyncStatusOne line that says where the person's changes are: Saved, Saving…, Offline (kept on this device) or Couldn't save, each with its icon, and Retry while there is a problem.
- InstallPromptA quiet offer to install the web app, shown only where the browser can install it (Chromium on Android and desktops), never while it already runs installed, and not again for two weeks after Not now.
Display
- SkeletonA shimmering placeholder in the shape of content that is still loading.
- AvatarA person's picture, or their initials until it loads or when it fails.
- BadgeA short label for a status, category or count: "Draft", "Vegan", "3".
- AlertAn inline message in the page: something saved, something failed, something to know before going on.
- SeparatorA thin line in the theme's border color between groups of content, horizontal or vertical.
- CardA surface that groups one thing's content: a media slot across the top, a title with a description and an action, a body, and a footer.
- EmptyWhat a list, search or page shows when it has nothing in it: an icon, a title that says what is empty, a sentence on what to do, and the action that does it.
- DescriptionListOne thing's details as pairs of a term and its value: a recipe's prep time and servings, an order's date and total, an account's email.
- CarouselA row of slides the user swipes or steps through with Previous and Next buttons: recipe photos, a few featured cards.
- CodeBlockCode or a command on a muted surface in the theme's monospace font, with a caption and a button that copies it.
Lists
- AccordionA stack of titles that each open their own content, for FAQs and long settings pages.
- CollapsibleOne section that opens and closes under its title, such as nutrition facts under a recipe.
- ShowMore"Show more" for a long list or a long text.
- ItemOne row of a list: leading media, a title with a description, and trailing actions.
- ItemGroupA list of
Itemrows, with an optional label that names it, lines between the rows, and what to show when it is empty. - SwipeActionsA list row with actions beside it that a horizontal swipe reveals: swipe toward the start for the
trailingactions (Delete, Archive), toward the end for theleadingones (Pin). - ReorderableA list the user puts in order: recipe steps, a queue, favorites.
- ChecklistA list of things to tick off, such as a recipe's ingredients or a shopping list: each row a checkbox the whole row toggles, with an optional value and action.
Layout
- ScrollAreaA scrolling region with a slim scrollbar that matches the theme, inside a height you set.
- AspectRatioA frame that keeps an image, video or map at a fixed shape while its width follows the layout, so the page does not jump when the media loads.
- StackLays its children out top to bottom with an even gap.
- RowLays its children out side by side with an even gap, centered up and down.
- ResizablePanels side by side (or stacked) with a draggable handle between each pair: a file list beside an editor, a preview above a console.
- PageHeaderThe top of a page: its title with an optional line above it (
eyebrow), a description under it, the page's actions beside it, and a trail and an image above.
Navigation
- TabsTabs that switch between panels in place: an accessible tab list with roving focus, arrow-key navigation, a line that slides to the selected tab, and 44px tabs on touch screens.
- SegmentedControlAn iOS-style segmented control: a row of equal segments with a raised thumb that slides to the checked one, for switching how one view shows its content in place, such as list or grid.
- NavbarThe bar across the top of an app: your brand, the main links and a few controls, with the current page marked
aria-current="page"and a bar at the start edge, distinct from hover and press highlights. - SidebarThe column of links down the side of an app, in sections, with the current page marked
aria-current="page"and a bar at the start edge, distinct from hover and press highlights. - SidebarLayoutThe shell of an app with a
Sidebar: the sidebar beside the page from 640px up, in view while the page scrolls, and a sticky top bar with the sidebar's menu button below 640px. - StackedLayoutThe shell of an app with a
Navbar: the bar across the top, in view while the page scrolls, and the page below it in a centered column. - AuthLayoutThe page for signing in, signing up or resetting a password: one
Cardin the middle of the screen, with your brand, the title as the page's<h1>, the form, and a line under the card. - BreadcrumbThe trail from the top of the site to the current page: a labelled
<nav>with an ordered list of links, the last item markedaria-current="page". - PaginationPage navigation for a long list: Previous, the page numbers with gaps, and Next, with the current page marked
aria-current="page". - NavigationMenuA row of links where some open a panel of further links, each with a line of description: the navigation of a site with more pages than fit in a bar.
- SkipLinkThe "Skip to main content" link a keyboard or screen-reader user meets first on every page, so one Tab and Enter jump past the header and navigation.
- TabBarThe bar of tabs at the bottom of a phone screen: two to five of the app's top-level pages, each an icon over a short label, with the current page marked
aria-current="page"and an accent wash.
Data
Chat
- MessageOne message in a chat: who wrote it, their avatar and what they wrote, with any attachments under it.
- MessageListA conversation:
Messages in a scrolling, labeled region that opens at the newest one. - AttachmentA file attached to a chat message, or waiting to be sent with one: its icon, name and size.
- ConversationListA list of conversations to choose from: each row shows the avatar, the title, when the latest message arrived and a line of it, and marks unread conversations with a bold title and a dot.
- AttentionCardSomething that waits on the person: a mention, a question asked of them or a request still unanswered.
- ReactionBarA message's reactions: each one's emoji and how many chose it, with the person's own pressed and tinted, and quick reactions to add with a single press.
App setup
Parts and app setup
Pages for the exports that install with another component, or with the helpers in lib/ouro.
- canShare
- colorSchemeScript
- copyText
- share
- useColorScheme
- claim
- Radio
- MenuBar
- MenuCheckboxItem
- MenuGroup
- MenuItem
- MenuRadioGroup
- MenuRadioItem
- MenuSeparator
- MenuSub
- buzz
- chime
- createChimeContext
- formatDuration
- resetTimer
- restoreTimer
- toast
- useInstallPrompt
- useTimer
- AvatarGroup
- ResizableHandle
- ResizablePanel
- ResizablePanelGroup
- ChartContainer
- ChartLegend
- ChartTooltip
- ColorSchemeProvider
- OuroProvider
Guides
- ClaimsA factual sentence in this repository is a claim: it carries the primary source it comes from and a check that it still holds, so the next reader, person or agent, can trust it without rebuilding the proof.
- The conformance matrixSome review findings come back again and again: focus lost when a control disappears, server HTML that a reader in another time zone or locale cannot hydrate, a part on the wrong side in a right-to-left page, a control that vanishes under forced colours, a message announced twice.
- FormsA form control is one component on the Field contract: pass
label,nameanderror, and wrap the controls in aFormthat takeserrorsstraight from your server action. - GuardrailsThe guardrail kits hold an app to Ouro UI: the aim is that every control a person can reach is an Ouro control, and the number that are not can only fall.
- InstallingAdd
ouro-baseonce per app, then add components; no later add changes your stylesheet or your test-tool versions. - The screen-reader laneOuro UI's components are read by real screen readers before every release: VoiceOver on macOS and NVDA on Windows, driven through Guidepup in this repository's CI.
- Static CSSOuro HX's tokens also come as plain stylesheets, for a page with no build step and no Tailwind: a status page, a report or a prototype written in HTML.
- Status dashboardsA status dashboard tells a person where some work stands: what is done, what failed, what is running, and what nobody has started.
- TestingOuro UI's tests install beside each component and run in your app, in real browsers, against your theme.
- Comparison results: app-shellComparison overview, scores, protocol and limits
- Comparison results: command-paletteComparison overview, scores, protocol and limits
- Comparison results: confirm-deleteComparison overview, scores, protocol and limits
- Comparison results: recipe-listComparison overview, scores, protocol and limits
- Comparison results: settings-formComparison overview, scores, protocol and limits
- Why Ouro HX needs no skillOuro HX puts component guidance in the source an agent already reads: required props, compiler hints and development messages.
- Switching from shadcnshadcn/ui components and props, and their Ouro HX equivalents.
- Updating installed componentsReview upstream changes, then overwrite and reapply your edits.