`. Pass `render={

}` (or the level that fits) when the empty state is a section of the page. - `` is hidden from assistive tech because the title already says what it means. Images in the default variant stay exposed, so give them an `alt` or `alt=""`. - When results disappear after a search or filter, announce the change with a short `role="status"` message next to the list. Don’t make the whole empty state a live region, since its buttons and links would be read every time. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/empty.md --- # Field > Labels, descriptions and errors wired to their control, with validation states and layouts for forms. Canonical: https://hextaui.com/docs/field Last updated: 2026-10-27 ## Usage ```tsx import { Field, FieldDescription, FieldError, FieldGroup, FieldLabel, } from "@/components/ui/field" ``` ```tsx Email We’ll never share it. ``` Put any HextaUI control inside a `` and it’s labelled, described and validated automatically. There’s no need to wire up `id`, `htmlFor` or `aria-describedby` by hand. ## Composition ### Single field One control with its label, help text and validation. ```text Field ├── FieldLabel ├── Input / Textarea / Select / … ├── FieldDescription ├── FieldError ├── FieldCounter └── FieldStatus ``` ### Horizontal field A switch or checkbox with its text beside it. ```text Field ├── Switch / Checkbox └── FieldContent ├── FieldLabel └── FieldDescription ``` ### Choice card A label that wraps a whole field, so the card is the click target. ```text FieldLabel └── Field ├── Checkbox / RadioGroupItem └── FieldContent ├── FieldTitle └── FieldDescription ``` ### Grouped fields Related fields, spaced evenly. ```text FieldGroup ├── Field ├── FieldSeparator └── Field ``` ### Fieldsets A titled group of fields, or a radio or checkbox group with an item per option. ```text FieldSet ├── FieldLegend ├── FieldDescription └── FieldGroup └── Field FieldSet ├── FieldLegend └── FieldItem ├── RadioGroupItem / Checkbox └── FieldLabel ``` ## Accessibility - The label, description and visible errors are linked to the control for you, so screen readers announce all three when it’s focused. - Invalid controls get `aria-invalid`, which also draws their error ring. - Errors are not live regions. They’re read when the control is focused, so validating on change doesn’t interrupt typing. On submit, move focus to the first invalid field. - Errors grow and fade in place instead of pushing content down. With reduced motion on, they appear without animating. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/field.md --- # Hover card > A preview card that opens when a link is hovered or focused, for content sighted users can glance at. Canonical: https://hextaui.com/docs/hover-card Last updated: 2026-10-27 ## Usage ```tsx import { HoverCard, HoverCardContent, HoverCardTrigger, } from "@/components/ui/hover-card" ``` ```tsx } />}> @hextaui Components built on shadcn/ui. ``` A hover card is a preview, not a menu or a dialog. The trigger stays a normal link, so everything in the card must also be on the page it links to. ## Composition ```text HoverCard ├── HoverCardTrigger └── HoverCardContent ``` ## Accessibility - The card is a visual extra for sighted mouse and keyboard users. Screen readers only hear the link, so they aren’t forced through a preview on every link they pass. - Nothing opens on touch screens, where there is no hover. A tap follows the link, which is why the destination has to hold the same information. - Focus never moves into the card. If it needs controls that must be reachable from the keyboard, use a popover instead. - With reduced motion on, the card fades without scaling, and a shared card jumps between links instead of gliding. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/hover-card.md --- # Input > A text input with three sizes, invalid and read-only states, native validation styling and a 16px touch font so phones never zoom in. Canonical: https://hextaui.com/docs/input Last updated: 2026-10-27 ## Usage ```tsx import { Input } from "@/components/ui/input" ``` ```tsx Email ``` ## Accessibility - Every input needs a name. Use a `` with `htmlFor`, or `aria-label` when there’s no visible label. A placeholder is not a label. - Connect helper and error text with `aria-describedby`, and set `aria-invalid` only once there is an error to show. - On touch screens the text is at least 16px, so iOS Safari doesn’t zoom the page when the input is focused. - Inside a Base UI `Field`, the label, description, error and validity are wired up for you. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/input.md --- # Input group > An input with icons, text, buttons or a keyboard hint attached, sharing one border and focus ring. Canonical: https://hextaui.com/docs/input-group Last updated: 2026-10-27 ## Usage ```tsx import { InputGroup, InputGroupAddon, InputGroupButton, InputGroupClear, InputGroupCount, InputGroupInput, InputGroupPasswordToggle, InputGroupText, InputGroupTextarea, } from "@/components/ui/input-group" ``` ```tsx ``` Put `` or `` first and the addons after it. Addons place themselves with `align`, so the field comes first in the tab order and for screen readers. The group tracks its field, so the smart parts need no wiring. ``, `` and `` read the value, `type` and `maxLength` from the field, whether it's controlled or not. ## Composition ```text InputGroup ├── InputGroupAddon │ ├── InputGroupText │ ├── InputGroupButton │ ├── InputGroupClear │ ├── InputGroupCount │ └── InputGroupPasswordToggle └── InputGroupInput / InputGroupTextarea ``` ## Accessibility - Every field needs a name. Use a visible label, a Field, or `aria-label`. Icons and addon text aren't part of the field's name. - Give icon-only buttons an `aria-label`. - When addon text carries meaning, like a currency or a domain, add it to the label or reference it with `aria-describedby`. - `` is skipped in the tab order because Escape does the same thing. The password toggle stays tabbable and keeps the same name, with `aria-pressed` reporting its state. - When a submit finds the field invalid, the group shakes once. With reduced motion the red border is the only cue. - On touch screens the field text is at least 16px so phones don't zoom in when it's focused. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/input-group.md --- # Input OTP > One-time code slots that take typing, paste and SMS autofill, with an opt-in animation that cascades codes in and a status for verifying. Canonical: https://hextaui.com/docs/input-otp Last updated: 2026-10-27 ## Usage ```tsx import { InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot, } from "@/components/ui/input-otp" ``` ```tsx Verification code ``` Render one `` per character and set `length` to the same number. Slots find their position on their own, so there is no `index` prop to keep in sync. ## Composition ```text InputOTP ├── InputOTPGroup │ └── InputOTPSlot ├── InputOTPSeparator └── InputOTPGroup └── InputOTPSlot ``` ## Accessibility - Each slot is a real input. The first takes its name from your `` or `aria-label`; the others are named "Character 2 of 6" and so on. Pass `aria-label` on a slot to translate it. - The first slot has `autocomplete="one-time-code"`, so iOS and macOS offer codes from Messages and Mail, Android offers SMS codes, and password managers can fill it. A whole code that lands in one slot is spread across all of them. The animated cascade runs for every source, including codes you set from the WebOTP API. - Whenever the code becomes empty while a slot has focus, such as after a wrong code is cleared, focus moves back to the first slot so the next attempt starts in the right place. - When `status` is set, a hidden live region next to the field announces it. Change the words with `loadingLabel`, `successLabel` and `errorLabel`. - With `animated`, characters are drawn on a layer hidden from screen readers while the inputs keep the real value. Under reduced motion, characters only fade and the status wave becomes a gentle pulse. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/input-otp.md --- # Item > A row of media, text and actions for lists, settings and pickers, with a grouped surface and a hover highlight that glides between rows. Canonical: https://hextaui.com/docs/item Last updated: 2026-10-27 ## Usage ```tsx import { Item, ItemActions, ItemChevron, ItemContent, ItemDescription, ItemGroup, ItemMedia, ItemTitle, } from "@/components/ui/item" ``` ```tsx }> Profile Name, photo and handle ``` Give icon media a `tone` for colored tiles like iOS Settings, or leave it unset for a neutral tile. An item becomes interactive when it renders as a link, button or label through `render`. Only then does it get hover, press and focus styles, so static rows never pretend to be clickable. ## Composition ```text ItemGroup ├── Item │ ├── ItemHeader │ ├── ItemMedia │ ├── ItemContent │ │ ├── ItemTitle │ │ └── ItemDescription │ ├── ItemActions │ ├── ItemChevron │ └── ItemFooter └── ItemSeparator ``` ## Accessibility - A group is a list when its items are plain rows. Items rendered as links or buttons keep their own role, and the group drops the list role so the markup stays valid. Render the group as `
` and items as `
` wrapping links if you want both. - `` and the chevron are hidden from screen readers. Give images real alt text when they carry meaning. - The highlight is decoration. Keyboard focus shows the focus ring, and the highlight never moves focus or changes the tab order. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/item.md --- # Kbd > Key caps for shortcuts that show the right symbols on every platform, read them out properly and press down with the real keys. Canonical: https://hextaui.com/docs/kbd Last updated: 2026-10-27 ## Usage ```tsx import { Kbd, KbdGroup } from "@/components/ui/kbd" ``` ```tsx K ``` Write shortcuts once with `keys` and they show as ⌘K on a Mac and Ctrl K on Windows and Linux. Or pass any content as children for full control. ## Composition ```text Kbd KbdGroup └── Kbd ``` ## Accessibility - Symbols like ⌘ and ⇧ are hidden from screen readers and replaced with their names, so `keys="mod+shift+p"` is read as "Command Shift P". - Caps render as ``, and a group nests them in another ``, which is how HTML marks a key combination. - Showing a shortcut doesn't bind it. Register the key handler yourself. - The press effect is decoration, with a color change in place of movement when reduced motion is on. Before hydration, every platform sees the Apple symbols. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/kbd.md --- # Label > A label that follows its control, dimming when it's disabled and marking it required or optional on its own. Canonical: https://hextaui.com/docs/label Last updated: 2026-10-27 ## Usage ```tsx import { Label } from "@/components/ui/label" ``` ```tsx Email ``` Point `htmlFor` at a control's `id`, or wrap the control. Either way the label finds it and follows its state. Inside a ``, use ``, which wires up the id for you. ## Accessibility - Clicking the label focuses or toggles its control, so it's a bigger target than the control alone. - Double-clicking the label text doesn't select it. Double-clicks on a control inside the label work as usual. - Every control needs a name. When there's no visible label, use `aria-label` on the control instead. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/label.md --- # Marker > Quiet notes between content, like date dividers and system events, with sticky dates and times that read as Today or Yesterday. Canonical: https://hextaui.com/docs/marker Last updated: 2026-10-27 ## Usage ```tsx import { Marker, MarkerContent, MarkerIcon, MarkerTime, } from "@/components/ui/marker" ``` ```tsx ``` ## Composition ```text Marker ├── MarkerIcon └── MarkerContent └── MarkerTime ``` ## Accessibility - Markers are plain text, so screen readers read them in place. Icons are hidden from them. - `` keeps the exact moment in `dateTime` while showing a friendly label. - The sticky pill appears without motion when reduced motion is on. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/marker.md --- # Menubar > A desktop-style bar of menus with one highlight that slides between open menus and instant switching as you sweep across. Canonical: https://hextaui.com/docs/menubar Last updated: 2026-10-27 ## Usage ```tsx import { Menubar, MenubarContent, MenubarItem, MenubarMenu, MenubarShortcut, MenubarTrigger, } from "@/components/ui/menubar" ``` ```tsx File New tab ⌘T ``` Each `` is a Dropdown menu, so items, checkbox and radio items, submenus, labels and shortcuts work and look exactly the same. Open a menu, then move the pointer or press the arrow keys to sweep across the bar. ## Composition ```text Menubar └── MenubarMenu ├── MenubarTrigger └── MenubarContent ├── MenubarGroup │ ├── MenubarLabel │ └── MenubarItem │ └── MenubarShortcut ├── MenubarCheckboxItem ├── MenubarRadioGroup │ └── MenubarRadioItem ├── MenubarSeparator └── MenubarSub ├── MenubarSubTrigger └── MenubarSubContent ``` ## Accessibility - Give the menubar a name with `aria-label`. It renders `role="menubar"` and each trigger is a menu item, so screen readers announce it as an application menu. - The bar is a single tab stop. Arrow keys move between menus, so the page's tab order stays short. - The sliding highlight is decoration. With reduced motion it just appears on the open menu. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/menubar.md --- # Message > A chat message row with an avatar, name, bubbles and status, where new messages rise in from the sender's side. Canonical: https://hextaui.com/docs/message Last updated: 2026-10-27 ## Usage ```tsx import { Message, MessageAvatar, MessageContent, MessageFooter, MessageGroup, MessageHeader, } from "@/components/ui/message" ``` ```tsx On my way. Read ``` A message lays out an avatar, a name, one or more ``s and a status line. Bubbles inherit the message's `align`, so you set it once. ## Composition ```text MessageGroup └── Message ├── MessageAvatar └── MessageContent ├── MessageHeader ├── Bubble └── MessageFooter ``` ## Accessibility - Messages are plain content. For a live chat, wrap the list in a `role="log"` element so screen readers read new messages as they arrive. - Put the sender's name in a header or in visually hidden text, since alignment alone doesn't say who wrote a message. - The entrance only plays for messages added after the list first renders. With reduced motion they fade in. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/message.md --- # Message scroller > A chat scroll area that follows new messages, keeps your place while you read back, and counts what you missed on the jump button. Canonical: https://hextaui.com/docs/message-scroller Last updated: 2026-10-27 ## Usage ```tsx import { MessageScroller, MessageScrollerButton, MessageScrollerContent, MessageScrollerItem, MessageScrollerProvider, MessageScrollerViewport, } from "@/components/ui/message-scroller" ``` ```tsx {messages.map((message) => ( … ))} ``` Give every item a stable `messageId`. The scroller uses it to follow new messages, keep your place and count what you haven't seen. Pair it with `` and `` for the rows. ## Composition ```text MessageScrollerProvider └── MessageScroller ├── MessageScrollerViewport │ └── MessageScrollerContent │ └── MessageScrollerItem └── MessageScrollerButton ``` ## Hooks Inside the provider, these hooks let your own controls scroll the thread and react to what's on screen. ```tsx const { scrollToEnd, scrollToMessage, scrollToStart } = useMessageScroller() const { start, end } = useMessageScrollerScrollable() const { visibleMessageIds, currentAnchorId } = useMessageScrollerVisibility() ``` ## Accessibility - The viewport is a labelled, focusable region and the content is a `role="log"`, so screen readers announce new messages as they arrive. Give the viewport an `aria-label`. - The jump button's label says how many messages are new, so "3 new messages" is read out, not just an arrow. - Following new messages never moves you while you're reading back. It only resumes once you're at the bottom again. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/message-scroller.md --- # Native select > The browser's own select, styled to match Input, with a quiet placeholder, Field support and the OS picker on every device. Canonical: https://hextaui.com/docs/native-select Last updated: 2026-10-27 ## Usage ```tsx import { NativeSelect, NativeSelectOptGroup, NativeSelectOption, } from "@/components/ui/native-select" ``` ```tsx Select a fruit Apple Banana ``` An option with an empty `value` acts as the placeholder: it shows in muted text until something is chosen. Put `className` on the select to size its wrapper, for example `w-full`. ## Composition ```text NativeSelect ├── NativeSelectOption └── NativeSelectOptGroup └── NativeSelectOption ``` ## Native select or Select? - Use Native select for simple lists, especially on phones, where the OS picker is the fastest and most familiar way to choose. - Use Combobox when people need to search, or when options need icons, descriptions or custom layouts. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/native-select.md --- # Navigation menu > Site navigation with dropdowns, or one full-width panel that stays open while its content slides between menus. Canonical: https://hextaui.com/docs/navigation-menu Last updated: 2026-10-27 ## Usage ```tsx import { NavigationMenu, NavigationMenuContent, NavigationMenuItem, NavigationMenuLink, NavigationMenuList, NavigationMenuTrigger, } from "@/components/ui/navigation-menu" ``` ```tsx Products Components Pricing ``` With `variant="panel"`, one card spans the whole bar. Moving between triggers keeps it open and in place: only the content slides toward the direction you moved, and the height eases to fit. Nothing closes, reopens or jumps. ## Composition ```text NavigationMenu └── NavigationMenuList ├── NavigationMenuItem │ ├── NavigationMenuTrigger │ └── NavigationMenuContent │ └── NavigationMenuLink └── NavigationMenuItem └── NavigationMenuLink ``` ## Accessibility - The root renders a ``. Give it an `aria-label` when the page has more than one. - Triggers are buttons that report whether their menu is open, and focus returns to them when the menu closes. - The content slide and the sliding highlight turn into fades when reduced motion is on. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/navigation-menu.md --- # Number flow > Animated numbers where only the changed digits spin, with any Intl format and locale. Canonical: https://hextaui.com/docs/number-flow Last updated: 2026-10-27 ## Usage ```tsx import { NumberFlow } from "@/components/ui/number-flow" ``` ```tsx ``` ## Accessibility - Screen readers read the real formatted number. The spinning columns are hidden from assistive tech, and characters that are leaving are hidden while they animate out. - It is not a live region. Wrap it in an element with `aria-live="polite"` when changes should be announced. - With reduced motion enabled, values update instantly with no spin. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/number-flow.md --- # Pagination > Page navigation that keeps every button in place, glides to the current page and jumps to any page from the ellipsis. Canonical: https://hextaui.com/docs/pagination Last updated: 2026-10-27 ## Usage ```tsx import { Pagination } from "@/components/ui/pagination" ``` ```tsx const [page, setPage] = React.useState(1) ``` Give `Pagination` a `count` and it builds the whole bar. It always shows the same number of slots, so Previous, Next and the numbers never shift under your cursor while you click through pages. Leave `count` out to compose the parts yourself. ## Composition ```text Pagination └── PaginationContent ├── PaginationItem │ └── PaginationPrevious ├── PaginationItem │ └── PaginationLink ├── PaginationItem │ └── PaginationEllipsis └── PaginationItem └── PaginationNext ``` ## Accessibility - The root is a `` labelled “Pagination”, and the current page has `aria-current="page"`. - At the first and last page, Previous and Next use `aria-disabled` instead of `disabled`, so focus isn't lost when you reach the end. - The sliding indicator becomes a fade when reduced motion is on. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/pagination.md --- # Popover > A floating panel anchored to a trigger that resizes smoothly with its content and follows the trigger’s direction. Canonical: https://hextaui.com/docs/popover Last updated: 2026-10-27 ## Usage ```tsx import { Popover, PopoverContent, PopoverDescription, PopoverHeader, PopoverTitle, PopoverTrigger, } from "@/components/ui/popover" ``` ```tsx }> Open Dimensions Set the dimensions for the layer. ``` ## Composition ```text Popover ├── PopoverTrigger └── PopoverContent ├── PopoverHeader │ ├── PopoverTitle │ └── PopoverDescription └── PopoverClose ``` ## Accessibility - `` and `` label and describe the popup for screen readers. Include a title whenever the popup contains more than a sentence. - Focus moves to the first focusable element when it opens and back to the trigger when it closes. Change this with `initialFocus` and `finalFocus`. - With reduced motion enabled, the popup fades without scaling. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/popover.md --- # Progress > A bar or ring that shows how far a task has come, eases between updates and slides while the total is unknown. Canonical: https://hextaui.com/docs/progress Last updated: 2026-10-27 ## Usage ```tsx import { Progress, ProgressCircle, ProgressLabel, ProgressValue, } from "@/components/ui/progress" ``` ```tsx Uploading ``` `` draws its own track and indicator after its children, so a label and value sit on one line above the bar. Each update eases the fill from where it is, so rapid updates read as one smooth motion instead of steps. ## Composition ```text Progress ├── ProgressLabel └── ProgressValue ProgressCircle └── ProgressValue ``` ## Accessibility - The root is a `progressbar` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax` and a formatted `aria-valuetext`. While indeterminate it has no current value. - `` names the bar. Without one, pass `aria-label`. - `` is hidden from screen readers, since the progressbar already announces the value. - With reduced motion, the fill jumps to each new value, and the indeterminate bar and ring pulse in place instead of moving. - Values are formatted in `en-US` unless you pass `locale`, so the server and browser render the same text. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/progress.md --- # Questionnaire > A step-by-step form that moves between questions with a sense of direction, shows real progress and answers from the keyboard. Canonical: https://hextaui.com/docs/questionnaire Last updated: 2026-10-27 ## Usage ```tsx import { Questionnaire, QuestionnaireActions, QuestionnaireChoice, QuestionnaireChoices, QuestionnaireItem, QuestionnaireNext, QuestionnairePrevious, QuestionnaireProgress, QuestionnaireSubmit, QuestionnaireTitle, } from "@/components/ui/questionnaire" ``` ```tsx What best describes your work? Design Engineering ``` Answers submit as a regular form, keyed by each item's `name`. Questions move toward the direction you go, the card eases to each question's height, and the progress fills only for questions that were answered or skipped. ## Composition ```text Questionnaire ├── QuestionnaireProgress ├── QuestionnaireItem │ ├── QuestionnaireTitle │ ├── QuestionnaireDescription │ ├── QuestionnaireChoices │ │ ├── QuestionnaireChoice │ │ │ └── QuestionnaireChoiceDescription │ │ └── QuestionnaireInput │ └── QuestionnaireError └── QuestionnaireActions ├── QuestionnairePrevious ├── QuestionnaireSkip ├── QuestionnaireNext └── QuestionnaireSubmit ``` ## Accessibility - Each `QuestionnaireItem` is a `` whose title is its ``. Inactive questions are hidden and inert, including the one animating out. - The progress is a `progressbar` that announces “Question 2 of 5”; the segments and spinning number are decorative. - Errors use `role="alert"` and the invalid answers get `aria-invalid`. - With reduced motion, questions switch instantly and nothing shakes. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/questionnaire.md --- # Radio group > Pick one option from a set, with a dot that hands off between choices and cards whose selection ring slides to the new pick. Canonical: https://hextaui.com/docs/radio-group Last updated: 2026-10-27 ## Usage ```tsx import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group" ``` ```tsx All new messages Direct messages and mentions ``` When the choice changes, the old dot shrinks away as the new one springs in, so the eye follows the pick instead of two things blinking at once. Wrap each item in a `` so the whole row is clickable. ## Composition ```text RadioGroup ├── RadioGroupItem └── RadioGroupCard ├── RadioGroupCardTitle └── RadioGroupCardDescription ``` ## Accessibility - Name the group with `aria-label`, `aria-labelledby` or a `FieldLegend`. - Each radio has a 36px hit area, and 44px on touch screens, while staying 16px on screen. - The dot and card ring don't move with reduced motion. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/radio-group.md --- # Resizable > Panels you can drag apart, with a quiet divider that wakes up on hover, sizes that glide on reset or collapse, and layouts that persist. Canonical: https://hextaui.com/docs/resizable Last updated: 2026-10-27 ## Usage ```tsx import { ResizableHandle, ResizablePanel, ResizablePanelGroup, } from "@/components/ui/resizable" ``` ```tsx Sidebar Content ``` Numbers are pixels and strings are percentages, so `defaultSize="30%"` and `minSize={240}` both work. The divider stays a hairline until you reach for it. While you drag, panels follow the pointer exactly; every other change glides, including double-click resets, keyboard steps and collapsing from code. ## Composition ```text ResizablePanelGroup ├── ResizablePanel ├── ResizableHandle └── ResizablePanel ``` ## Accessibility - Each divider is a focusable `separator` that reports the size of the panel before it. - The size readout is decorative; screen readers get the separator's own value. - With reduced motion, sizes change instantly and the divider doesn't animate. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/resizable.md --- # Scroll area > Native scrolling with a minimal scrollbar, edges that fade only where there’s more to see, and an optional peek that cuts the last item in half. Canonical: https://hextaui.com/docs/scroll-area Last updated: 2026-10-27 ## Usage Give the scroll area a fixed height or width. Content beyond it scrolls with the native scroll behavior, and a thin scrollbar appears while you hover or scroll. ```tsx import { ScrollArea } from "@/components/ui/scroll-area" ``` ```tsx {/* long content /} ``` ## Accessibility - Give the scroll area an `aria-label` when its purpose isn’t clear from the surrounding content, like the “Messages” label in the chat example. - The focus ring is drawn on the scroll area itself, so it stays visible above the faded edges. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/scroll-area.md --- # Select > Pick one or more options from a list that opens on the current value, with typeahead, groups and form support. Canonical: https://hextaui.com/docs/select Last updated: 2026-10-27 ## Usage ```tsx import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue, } from "@/components/ui/select" ``` ```tsx ``` The list opens right over the trigger with the current option lined up on top of the value, so your eye never loses its place. Pass `items` so `SelectValue` shows labels instead of raw values. For long lists that need searching, use Combobox. ## Composition ```text Select ├── SelectTrigger │ └── SelectValue └── SelectContent ├── SelectGroup │ ├── SelectLabel │ └── SelectItem └── SelectSeparator ``` ## Accessibility - Label the trigger with `FieldLabel` or `aria-label`. - On touch, the list opens below the trigger instead of over it, so your finger doesn't land on an option. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/select.md --- # Separator > A hairline that divides content horizontally or vertically, with an optional label and a decorative mode for purely visual lines. Canonical: https://hextaui.com/docs/separator Last updated: 2026-10-27 ## Usage ```tsx import { Separator } from "@/components/ui/separator" ``` ```tsx Or continue with ``` The line is one physical pixel thick on every screen, the same hairline as borders, so it lines up with cards and inputs around it. Space it with the parent's `gap` or a margin. ## Accessibility - A plain separator has `role="separator"` and `aria-orientation`, like an ``. - With `decorative`, it gets `role="none"` and screen readers skip it. - A separator with a label has no role. The separator role would make its text presentational, so the label is read as plain text instead. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/separator.md --- # Sheet > A panel that slides in from any edge, with swipe-to-dismiss, scroll lock and stacked nesting. Canonical: https://hextaui.com/docs/sheet Last updated: 2026-10-27 ## Usage ```tsx import { Sheet, SheetBody, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle, SheetTrigger, } from "@/components/ui/sheet" ``` ```tsx }>Open Edit profile Make changes to your profile. {/ content */} }>Save changes ``` ## Composition ```text Sheet ├── SheetTrigger └── SheetContent ├── SheetHeader │ ├── SheetTitle │ └── SheetDescription ├── SheetBody └── SheetFooter └── SheetClose ``` ## Accessibility - The sheet is a modal dialog. `` labels it and `` describes it, so always include a title. - Page scroll is locked and content behind it is hidden from assistive tech while it is open. - The close button is labelled “Close”. The handle on the inner edge shows the sheet can be dragged and is hidden from assistive tech. - With reduced motion enabled, the sheet fades in and out instead of sliding. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/sheet.md --- # Sidebar > An app sidebar that collapses to icons or off canvas, stays pinned under your header, and becomes a swipeable sheet on phones. Canonical: https://hextaui.com/docs/sidebar Last updated: 2026-10-27 ## Usage ```tsx import { Sidebar, SidebarContent, SidebarFooter, SidebarGroup, SidebarGroupContent, SidebarGroupLabel, SidebarHeader, SidebarInset, SidebarMenu, SidebarMenuButton, SidebarMenuItem, SidebarProvider, SidebarTrigger, } from "@/components/ui/sidebar" ``` Wrap your layout in `` and put the page in ``, after the sidebar. ```tsx export default function Layout({ children }: { children: React.ReactNode }) { return ( {children} ) } ``` ```tsx export function AppSidebar() { return ( Application } isActive> Home ) } ``` ## Composition ```text SidebarProvider ├── Sidebar │ ├── SidebarHeader │ ├── SidebarContent │ │ └── SidebarGroup │ │ ├── SidebarGroupLabel │ │ ├── SidebarGroupAction │ │ └── SidebarGroupContent │ │ └── SidebarMenu │ │ └── SidebarMenuItem │ │ ├── SidebarMenuButton │ │ ├── SidebarMenuAction │ │ ├── SidebarMenuBadge │ │ └── SidebarMenuSub │ │ └── SidebarMenuSubItem │ │ └── SidebarMenuSubButton │ ├── SidebarFooter │ └── SidebarRail └── SidebarInset └── SidebarTrigger ``` - `SidebarProvider` holds the open state, the keyboard shortcut and the widths. - `Sidebar` is a column that stays pinned while the page scrolls. Below 768px it becomes a sheet. - `SidebarHeader` and `SidebarFooter` stay in place. `SidebarContent` scrolls between them. - `SidebarGroup` is a section with an optional label and action. `SidebarMenu` holds the links. - `SidebarInset` is the page next to the sidebar. ## Width The sidebar is 16rem wide, 18rem on phones and 3rem when collapsed to icons. Override `--sidebar-width`, `--sidebar-width-mobile` and `--sidebar-width-icon` on the provider. ```tsx ``` ## Persisting the state The sidebar has no side effects. To remember whether it was open, save it in `onOpenChange` and read it back into `defaultOpen` when rendering on the server. ```tsx "use client" export function Providers({ defaultOpen, children, }: { defaultOpen: boolean children: React.ReactNode }) { return ( { document.cookie = `sidebar_state=${open}; path=/; max-age=604800` }} > {children} ) } ``` ## Accessibility - `SidebarTrigger` is labelled “Toggle Sidebar” and exposes `aria-expanded` and `aria-controls`. - `isActive` sets `aria-current="page"`. - Collapsing off canvas hides the content from keyboard and screen readers. If focus was inside, it moves to the trigger. - Collapsed to icons, labels stay in each link's accessible name and show as a tooltip on hover and keyboard focus. Group labels, actions and badges are hidden. - On phones the sidebar is a modal sheet: focus is trapped, swiping or Esc closes it, and following a link closes it. Links that open a new tab, downloads and modified clicks keep it open. - With reduced motion enabled, collapsing is instant. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/sidebar.md --- # Skeleton > Placeholders that wait 150ms before showing, take the exact size of the content they wrap, and fade it in without moving anything. Canonical: https://hextaui.com/docs/skeleton Last updated: 2026-10-27 ## Usage Use a skeleton on its own as a sized placeholder, or pass `loading` and wrap the real content so the placeholder takes its exact size. ```tsx import { Skeleton, SkeletonText } from "@/components/ui/skeleton" ``` ```tsx {user.name} ``` ## Accessibility - A skeleton on its own is decorative and hidden from assistive tech, and so is ``. - A skeleton wrapping content sets `aria-busy` while loading. The content underneath is hidden from assistive tech and can’t be focused until it loads. - Skeletons don’t announce anything. When people need to know what is loading, add a visible label or a status message. - With reduced motion enabled, skeletons appear right away without shimmer, pulse or fade. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/skeleton.md --- # Slider > Pick a value or a range by dragging, tapping the track or using the keys, with jumps that glide and an optional value bubble. Canonical: https://hextaui.com/docs/slider Last updated: 2026-10-27 ## Usage ```tsx import { Slider, SliderLabel, SliderValue } from "@/components/ui/slider" ``` ```tsx Volume ``` `` draws one thumb per value, so a number or a one-item array makes a single slider and two items make a range. Children such as `` and `` sit on one line above the track. While you drag, the thumb follows the pointer exactly. When the value jumps, from a press on the track, a key or a new controlled value, the thumb and fill glide there in 180ms instead of teleporting. ## Composition ```text Slider ├── SliderLabel └── SliderValue ``` ## Accessibility - Each thumb holds a native `input type="range"`, so it is a `slider` with its own value, min and max. - `` names every thumb. Without one, `aria-label` on `` is passed to the thumbs, not the wrapper, so the slider is never left unnamed. In a range, use `getAriaLabel` to tell the thumbs apart. - `` and the value bubble are not announced on every change; the thumb already reports its value. - Pressing a thumb doesn't show a focus ring; the arrow keys do. With reduced motion the thumb jumps instead of gliding. - On touch screens the hit area grows to at least 44px without changing the layout. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/slider.md --- # Spinner > A loading indicator with Apple-style ticks or a breathing ring that can wait before showing and stay long enough not to flicker. Canonical: https://hextaui.com/docs/spinner Last updated: 2026-10-27 ## Usage ```tsx import { Spinner } from "@/components/ui/spinner" ``` ```tsx ``` The default is the eight-spoke indicator from Apple platforms. `variant="ring"` spins while its arc grows and shrinks, so it reads as working rather than stuck. Both are drawn in the current text color. ## Accessibility - On its own, the spinner is a `status` named by `label` (“Loading”). - With `aria-hidden`, it drops its role, for use beside visible text or inside a busy button. - With reduced motion, it gently pulses instead of spinning, so it still shows that something is happening. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/spinner.md --- # Switch > An on/off toggle you can tap, press or drag, with a thumb that stretches under your finger and an optional pending state for saves. Canonical: https://hextaui.com/docs/switch Last updated: 2026-10-27 ## Usage ```tsx import { Switch } from "@/components/ui/switch" ``` ```tsx Wi-Fi ``` Press and the thumb stretches toward the other side before springing across, so you feel the press land. You can also grab the thumb and drag it: past the middle it flips, short of it it snaps back. ## Accessibility - The switch is a `switch` role named by its label. Wrap it in a `` or use `Field`. - While saving, it's `aria-busy` and ignores new presses. - The hit area is larger than the switch, and larger again on touch. - With reduced motion, the thumb moves instantly and nothing shakes. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/switch.md --- # Table > A responsive table with a surface style, wrapping or compact cells, sticky headers, pinned columns and scroll hints. Canonical: https://hextaui.com/docs/table Last updated: 2026-10-27 ## Usage ```tsx import { Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, } from "@/components/ui/table" ``` ```tsx Invoice Amount INV-0418 $2,400.00 ``` Use `` for the cell that names each row. It reads as the row's header to screen readers and gets a stronger text color. For sorting, filtering and selection, build on ``. ## Composition ```text Table ├── TableCaption ├── TableHeader │ └── TableRow │ └── TableHead ├── TableBody │ └── TableRow │ └── TableCell └── TableFooter └── TableRow └── TableCell ``` ## Accessibility - The parts render native table elements, so screen readers announce rows, columns and headers without extra roles. - Mark the cell that names a row with `` so each value is read with its row and column. - The scroll area only joins the tab order while it overflows, so tables that fit don't add an extra stop. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/table.md --- # Tabs > Switch between views with an indicator that slides to the active tab, as a segmented control or an underline, and lists that scroll when they overflow. Canonical: https://hextaui.com/docs/tabs Last updated: 2026-10-27 ## Usage ```tsx import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs" ``` ```tsx Overview Analytics … … ``` One indicator slides to the active tab and resizes to fit it, while the content switches instantly so frequent switching never waits on an animation. The indicator is placed before the page hydrates, so it never jumps in on load. ## Composition ```text Tabs ├── TabsList │ └── TabsTrigger └── TabsContent ``` ## Accessibility - The list is a `tablist`; each trigger is a `tab` that controls its `tabpanel`. - Panels are focusable, so keyboard users can reach content that has no links or buttons. - With reduced motion, the indicator jumps instead of sliding. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/tabs.md --- # Textarea > Multi-line text that grows smoothly with what you write between a minimum and maximum number of rows, with counters, validation and a submit shortcut. Canonical: https://hextaui.com/docs/textarea Last updated: 2026-10-27 ## Usage ```tsx import { Textarea } from "@/components/ui/textarea" ``` ```tsx ``` The box grows with your text, easing to each new line instead of jumping, from `minRows` up to `maxRows`, then scrolls. Typing is never delayed by the animation. ## Accessibility - Label it with `FieldLabel` or `aria-label`. - On touch screens the text is at least 16px, so iOS doesn't zoom in when it's focused. - The shortcut waits while an input method is composing, so confirming a Japanese or Chinese word never sends the message. - With reduced motion, the box resizes instantly. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/textarea.md ---  # Toast > Brief messages that stack neatly, expand on hover, swipe away, and turn a loading state into success or error in place. Canonical: https://hextaui.com/docs/toast Last updated: 2026-10-27 ## Usage Add `<Toaster />` once, near the root of your app. ```tsx import { Toaster } from "@/components/ui/toast" export default function RootLayout({ children }) { return ( <html lang="en"> <body> {children} <Toaster /> </body> </html> ) } ``` Then call `toast` from anywhere, including outside React components. ```tsx import { toast } from "@/components/ui/toast" toast("Event created", { description: "Sunday at 9:00 AM" }) toast.success("Payment received") toast.promise(save(), { loading: "Saving…", success: "Saved", error: "Couldn't save" }) ``` Toasts stack into a neat pile with the newest in front. Hover or focus the pile to fan it out; every timer pauses while you read. Swipe a toast toward its edge to dismiss it. ## Accessibility - Toasts are announced politely; `toast.error` is announced right away. - Timers pause while the pointer or focus is on the toasts, so nobody has to race a countdown. - Close buttons appear on hover and focus, and are always visible on touch screens. - With reduced motion, toasts fade instead of sliding. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/toast.md ---  # Toggle > A button that stays on or off, with a fill that settles in when pressed, a clear hover-to-on step and icons that can fill with the state. Canonical: https://hextaui.com/docs/toggle Last updated: 2026-10-27 ## Usage ```tsx import { Toggle } from "@/components/ui/toggle" ``` ```tsx <Toggle aria-label="Bold"> <IconBold /> </Toggle> ``` Hovering an off toggle shows a light tint; turning it on settles a stronger fill into place and brings the label to full contrast, so on never looks like hover. ## Accessibility - The toggle is a `button` with `aria-pressed`, so screen readers announce whether it's on. - Give icon-only toggles an `aria-label` that names the action ("Mute microphone") and keep it the same in both states. Changing it as well as the pressed state reads as a double negative. - On touch screens the hit area grows to at least 44px, except inside a toggle group where neighbours would overlap. - With reduced motion, nothing scales; the fill only fades. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/toggle.md ---  # Toggle group > A row of toggles for one choice or many, with a fill that slides to the picked item, joined or spaced items and arrow-key focus. Canonical: https://hextaui.com/docs/toggle-group Last updated: 2026-10-27 ## Usage ```tsx import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group" ``` ```tsx <ToggleGroup aria-label="Date range" defaultValue={["week"]}> <ToggleGroupItem value="day">Day</ToggleGroupItem> <ToggleGroupItem value="week">Week</ToggleGroupItem> <ToggleGroupItem value="month">Month</ToggleGroupItem> </ToggleGroup> ``` When one item can be on at a time, a single fill slides to the picked item and takes its shape, so the group reads as one control. With `multiple`, each item fills on its own. The fill is placed before the first paint, so it never slides in on load. ## Composition ```text ToggleGroup └── ToggleGroupItem ``` ## Accessibility - The group has the `group` role; give it an `aria-label`. Each item is a button with `aria-pressed`. - Only one item is in the tab order, so the group is a single Tab stop and arrow keys move inside it. - Without `multiple`, pressing the picked item turns it off. Control the value to keep one item on. - With reduced motion, the fill fades instead of sliding. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/toggle-group.md ---  # Tooltip > A short hint on hover or keyboard focus that opens after a brief rest, switches instantly between neighbours and shows shortcuts. Canonical: https://hextaui.com/docs/tooltip Last updated: 2026-10-27 ## Usage ```tsx import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, } from "@/components/ui/tooltip" ``` ```tsx <Tooltip> <TooltipTrigger render={<Button variant="ghost" size="icon" aria-label="Undo" />}> <IconArrowBackUp /> </TooltipTrigger> <TooltipContent>Undo</TooltipContent> </Tooltip> ``` A tooltip opens after a short rest on the trigger, or right away when the trigger gets keyboard focus. Once one is showing, its neighbours open instantly and without animation, so scanning a toolbar feels like reading labels rather than waiting for each one. That instant switching works between tooltips that share a `TooltipProvider`. Wrap your app (or a toolbar) in one to share the delay. A tooltip without a provider still works on its own with the same defaults. ```tsx <TooltipProvider> <App /> </TooltipProvider> ``` ## Composition ```text TooltipProvider └── Tooltip ├── TooltipTrigger └── TooltipContent TooltipGroup └── TooltipTrigger ``` ## Accessibility - A tooltip is a visual hint, not a label. Give icon-only triggers an `aria-label` that matches the tooltip text. - Nothing opens on touch, and a tap only does what the trigger does. Don’t put anything in a tooltip that people need; use a popover for that. - Pointer users can move onto the tooltip to read or select it without it closing. - With reduced motion on, the tooltip fades without scaling. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/tooltip.md ---  # Tree > Nested, expandable rows for files and hierarchies, with indent guides, connector lines, cascading checkboxes, typeahead and full keyboard support. Canonical: https://hextaui.com/docs/tree Last updated: 2026-10-27 ## Usage ```tsx import { Tree, TreeGroup, TreeItem, TreeItemLabel, } from "@/components/ui/tree" ``` ```tsx <Tree aria-label="Files" defaultExpandedValues={["src"]}> <TreeItem value="src"> <TreeItemLabel icon={<IconFolder />}>src</TreeItemLabel> <TreeGroup> <TreeItem value="index"> <TreeItemLabel icon={<IconFile />}>index.ts</TreeItemLabel> </TreeItem> </TreeGroup> </TreeItem> </Tree> ``` An item with a `<TreeGroup />` is a branch: it gets a chevron, opens and closes, and answers to the arrow keys. Every item needs a `value` that is unique within the tree. ## Composition ```text Tree └── TreeItem ├── TreeItemLabel └── TreeGroup └── TreeItem └── TreeItemLabel ``` ## Accessibility The tree follows the WAI-ARIA tree view pattern. Each row is the `treeitem` and owns its group through `aria-owns`, so a row’s name is only its own label and link rows work as real links. Only one row is in the tab order at a time. When a branch closes around the focused row, focus moves to that branch instead of getting lost. Closed groups stay in the page, so the browser’s find-in-page opens the folders around a match, and checking a branch sees every item inside it. Give the tree an `aria-label`. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/tree.md ---  # Video player > A video player with a scrubbable seek bar, auto-hiding controls, keyboard shortcuts, speed, picture in picture and full screen. Canonical: https://hextaui.com/docs/video-player Last updated: 2026-10-27 ## Usage ```tsx import { VideoPlayer, VideoPlayerContent, VideoPlayerControls, VideoPlayerFullscreenButton, VideoPlayerPlayButton, VideoPlayerSeekBar, VideoPlayerSpacer, VideoPlayerTime, VideoPlayerVolume, } from "@/components/ui/video-player" ``` ```tsx <VideoPlayer> <VideoPlayerContent src="/intro.mp4" poster="/intro.jpg" /> <VideoPlayerControls> <VideoPlayerSeekBar /> <VideoPlayerPlayButton /> <VideoPlayerVolume /> <VideoPlayerTime /> <VideoPlayerSpacer /> <VideoPlayerFullscreenButton /> </VideoPlayerControls> </VideoPlayer> ``` ## Composition ```text VideoPlayer ├── VideoPlayerContent └── VideoPlayerControls ├── VideoPlayerPlayButton ├── VideoPlayerSeekButton ├── VideoPlayerSeekBar ├── VideoPlayerTime ├── VideoPlayerSpacer ├── VideoPlayerVolume ├── VideoPlayerPlaybackRate ├── VideoPlayerCaptionsButton ├── VideoPlayerPictureInPictureButton └── VideoPlayerFullscreenButton ``` ## Accessibility - The player is a labelled region. Every button has a name that follows its state (Play, Pause, Replay) and a tooltip with its shortcut. - The seek bar and volume are sliders. The seek bar reads its value as “1 minute 5 seconds of 3 minutes”. - Actions from shortcuts and video clicks are announced politely, for example “Paused” or “Volume 40%”. Load errors are announced as an alert. - In the overlay variant, controls fade out after 2.5 seconds of playback without pointer movement. They stay visible while paused, while you hover or use them with the keyboard, and while a menu is open. - On touch screens, a tap shows or hides the controls and a double tap on the left or right third goes back or forward 10 seconds. Keep tapping to add 10 seconds each time. - The captions button is a toggle with `aria-pressed`. It picks the last track you used, then one in the browser’s language, then the first one. - With reduced motion, controls and feedback fade without moving or scaling. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/video-player.md ---  # useAutosize > Grows a textarea with what you write between its minimum and maximum height, animating each change without ever touching the text. Canonical: https://hextaui.com/docs/use-autosize Last updated: 2026-10-27 ## Usage ```tsx import { useAutosize } from "@/hooks/use-autosize" ``` ```tsx const ref = React.useRef<HTMLTextAreaElement>(null) useAutosize(ref, true, value) <textarea ref={ref} rows={1} value={value} onChange={(event) => setValue(event.target.value)} className="min-h-[calc(1lh+1rem)] max-h-[calc(8lh+1rem)] resize-none" /> ``` `<Textarea autoResize>` already uses this hook. Call it yourself when you render your own `<textarea>`, such as a chat composer or an inline editor. ## How it works On each change the hook sets the height to `auto`, reads the natural `scrollHeight`, and clamps it to the element's own CSS `min-height` and `max-height`. All of that happens before paint, so you never see the collapsed frame. The bounds stay in your CSS, so they can be responsive or use `lh` to count lines. ```bash min-h-[calc(2lh+1rem)] at least two lines plus the vertical padding max-h-[calc(8lh+1rem)] then scroll after eight max-h-64 or any fixed length ``` - Height changes animate over 180ms, and a change that comes in mid-animation starts from the current height, so fast typing never jumps. Under reduced motion the height snaps. - Past `max-height` the textarea scrolls. Otherwise its scrollbar stays hidden, so it doesn't flash on each new line. - It refits when the width changes, because text that wraps differently changes the height. - It listens for `input` on `window` and only measures. It never reads or writes the value, so keystrokes are never delayed or dropped. ## Good to know - Set `rows={1}` and `resize-none`. A manual resize handle fights the automatic height. - Turning `enabled` off or unmounting removes the inline height and overflow, handing the size back to your CSS. - On touch screens, use at least 16px text in the textarea, or iOS zooms in when it's focused. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/use-autosize.md ---  # useButtonFeedback > Runs an async action through loading, success and error, skipping the spinner for fast requests and holding an error while you read it. Canonical: https://hextaui.com/docs/use-button-feedback Last updated: 2026-10-27 ## Usage ```tsx import { useButtonFeedback } from "@/hooks/use-button-feedback" ``` ```tsx const { buttonProps, track } = useButtonFeedback() <form onSubmit={(event) => { event.preventDefault() track(() => saveProfile(new FormData(event.currentTarget))) }}> … <Button type="submit" {...buttonProps}>Save</Button> </form> ``` `<Button feedback>` runs this flow for you when its `onClick` returns a promise. Use the hook when the work starts somewhere else, like a form's `onSubmit`, a keyboard shortcut or a blur. It also works when the status belongs on something that isn't a button. ## How it works `track()` takes a promise, or a function that returns one, and moves `status` through `idle`, `loading`, then `success` or `error`, and back to `idle`. The timing is what makes it feel calm. | Step | Description | | --- | --- | | `0–150ms` | Status stays idle. A request that settles in this window goes straight to success or error, without a spinner. | | `loading` | Shown from 150ms. Once shown it lasts at least 400ms, so it never flashes. | | `success` | Held for 2 seconds by default, then returns to idle. | | `error` | Held for 4 seconds by default. While the pointer is over the button, or it has keyboard focus, the reset waits until they leave, plus 600ms. | - Calls to `track()` while a request is in flight are ignored, so a double click or a held Enter key never sends the request twice. - A function passed to `track()` that throws synchronously is treated like a rejected promise. - `reset()` returns to idle at once. Whatever the abandoned request does later is ignored, and so is anything that settles after the component unmounts. - The error hold only counts a real mouse hover and keyboard focus. Touch has no hover, and a click's focus isn't `:focus-visible`, so neither one pins the error. ## Good to know - Give each button its own hook. Two buttons sharing one `buttonProps` both show the same status. - `onStatusChange` and `onError` always call the latest function you passed, so inline functions are fine. - Use `isPending()` to guard work outside `track()`. It reads a ref, so it's accurate even before the next render. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/use-button-feedback.md ---  # useComposedRef > Keeps a ref to your own element while still forwarding it to whatever ref the parent passed in. Canonical: https://hextaui.com/docs/use-composed-ref Last updated: 2026-10-27 ## Usage ```tsx import { useComposedRef } from "@/hooks/use-composed-ref" ``` ```tsx function SearchInput({ ref, ...props }: React.ComponentProps<"input">) { const [inputRef, setRef] = useComposedRef<HTMLInputElement>(ref) React.useEffect(() => { inputRef.current?.select() }, [inputRef]) return <input ref={setRef} {...props} /> } ``` In React 19, `ref` is a regular prop. When your component also needs the element for itself, you have two refs and only one `ref` attribute. This hook gives you an object ref to read, plus a callback that fills both refs. ## The problem it solves ```tsx function SearchInput({ ref, ...props }: React.ComponentProps<"input">) { const inputRef = React.useRef<HTMLInputElement>(null) return <input ref={inputRef} {...props} /> } ``` This compiles, but the parent's `ref` is dropped, so `ref.current` stays `null` in the parent. With `useComposedRef`, both the parent and the component get the element. - The returned `inputRef` is a normal `RefObject`, so you can pass it to hooks that expect one, like `useAutosize` or `useInvalidShake`. - `setRef` keeps the same identity while the parent's ref does, so React doesn't detach and reattach it on every render. - Works with object refs, callback refs and no ref at all. ## Composed or merged Use `useComposedRef` when you combine exactly one forwarded ref with your own object ref, which is most components. Use [useMergedRef](https://hextaui.com/docs/use-merged-ref) when you combine more than two, when one of them is a callback ref from another hook, or when a forwarded callback ref returns a React 19 cleanup function. `useComposedRef` calls a callback ref with `null` on detach instead of running its cleanup. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/use-composed-ref.md ---  # useDelayedLoading > Shows a loading state only when work is actually slow, then keeps it up long enough that it never flickers. Canonical: https://hextaui.com/docs/use-delayed-loading Last updated: 2026-10-27 ## Usage ```tsx import { useDelayedLoading } from "@/hooks/use-delayed-loading" ``` ```tsx const { data, isFetching } = useQuery(query) const showSpinner = useDelayedLoading(isFetching) return showSpinner ? <Spinner /> : <Results data={data} /> ``` Pass the raw loading flag and render from the boolean it returns. Most requests on a warm connection finish in under 150ms. Showing a spinner for those is worse than showing nothing: it flashes for a frame or two and reads as a glitch, not as progress. ## How it works The hook applies two rules. It waits for `delay` before showing anything, so work that finishes sooner never shows a loading state. Once the indicator is visible, it stays for at least `minDuration`, so it can't appear and vanish within a few frames. | Work takes | Description | | --- | --- | | `80ms` | Nothing is shown. | | `250ms` | Shown at 150ms and held until 550ms, the 400ms minimum. | | `900ms` | Shown at 150ms and hidden as soon as work ends. | The 400ms minimum is long enough to register as a deliberate state and short enough not to slow anyone down. - If `loading` turns back on while the indicator is still visible, it simply stays visible. There's no hide and show again. - Timers are cleared when the inputs change or the component unmounts, so nothing updates state after it's gone. - On the server and during the first render it returns `false`, so it never adds a hydration mismatch. ## Good to know - `<Spinner loading={...} />` and `<Button loading>` already use these timings. Reach for the hook when you render something else. - Keep the space the indicator will take, as the examples do, so the layout doesn't shift when it appears. - Pair it with an `aria-busy` or a status message. The hook only decides what to show visually. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/use-delayed-loading.md ---  # useHeldKeys > The keys someone is holding down right now, shared by every subscriber through a single set of window listeners. Canonical: https://hextaui.com/docs/use-held-keys Last updated: 2026-10-27 ## Usage ```tsx import { useHeldKeys } from "@/hooks/use-held-keys" ``` ```tsx const held = useHeldKeys(true) const showShortcutHints = held.has("meta") || held.has("ctrl") ``` Use it for anything that reacts to keys being held rather than pressed: keycaps that press down, shortcut hints that appear while you hold ⌘, or a modifier that switches a tool, like Alt to duplicate while dragging. ## How it works Every component that calls the hook shares one store. The first subscriber adds passive `keydown` and `keyup` listeners to `window`, and the last one to unsubscribe removes them. A page with fifty listening keycaps still has one pair of listeners. The listeners only read events. They never call `preventDefault`, and they sit on `window`, after React's own handlers, so typing in a field is never delayed or changed. ```bash "meta" "ctrl" "alt" "shift" modifiers, left and right alike "a" … "z" "0" … "9" letters and digits, by physical key "space" "enter" "escape" "tab" named keys, lowercased "arrowup" "arrowdown" "f1" … ``` - Letters and digits come from `event.code`, the physical key, so holding Option+K on a Mac still reports `k` rather than `˚`. - Key repeat is ignored, and nothing re-renders while a key is held. - macOS doesn't send `keyup` for other keys while ⌘ is down. When ⌘ is released, the store keeps only the modifiers still held, so letters can't get stuck. - Everything is released when the window loses focus or the tab is hidden. A shortcut that switches apps leaves nothing held. ## Good to know - Pass `false` to stop listening. The hook then returns an empty set and adds no listeners, so it's cheap to call it unconditionally. - The set is replaced only when a key goes down or up, so its identity works as a memo or effect dependency. - For shortcuts that fire an action, use `matchesHotkey` from `Hotkey` in a keydown handler instead. Holding keys is for showing state, not for running commands. - On the server, and before hydration, the set is empty. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/use-held-keys.md ---  # useInvalidShake > Shakes a form control when a submit attempt finds it invalid, and never while someone is still typing. Canonical: https://hextaui.com/docs/use-invalid-shake Last updated: 2026-10-27 ## Usage ```tsx import { useInvalidShake } from "@/hooks/use-invalid-shake" ``` ```tsx const ref = React.useRef<HTMLSelectElement>(null) useInvalidShake(ref) <form> <select ref={ref} required className="data-shake:motion-safe:animate-button-shake" > … </select> <button type="submit">Continue</button> </form> ``` The hook only sets a `data-shake` attribute. The motion comes from the theme's `animate-button-shake`, which you attach with `data-shake:motion-safe:animate-button-shake`. HextaUI's Input, Textarea, Native select and Input group already include that class and call the hook. Use it directly for your own controls. ## When it shakes A shake answers one question: why didn't my submit work? So the hook only shakes right after someone tries to submit, and never while they're still filling in the form. | Event | Description | | --- | --- | | `Submit attempt` | Clicking a submit button, pressing Enter in an input of the form, or the form's submit event. | | `Invalid within 600ms` | The control fires invalid, or has aria-invalid="true", data-invalid or :user-invalid. That covers native validation, Base UI fields and server errors set right after submitting. | | `Shake` | data-shake is set for 400ms. It shakes once per attempt, however many of those signals arrive. | - Inside an `InputGroup`, the whole group shakes, not just the inner control. - Under reduced motion, nothing is set. Pair the shake with a visible error message either way, since the shake is a cue, not the message. - The hook needs the control to belong to a `<form>`. Without one, it does nothing. ## Good to know - Turn it off per control with the `enabled` argument, or with `shake={false}` on HextaUI's inputs. - Restarting the attribute restarts the animation, so a second failed attempt shakes again even if the first is still running. - Native validation focuses the first invalid control on submit. The shake only adds motion on top of that and never moves focus. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/use-invalid-shake.md ---  # useMergedRef > Combines any number of callback and object refs into one, with React 19 ref cleanup for each of them. Canonical: https://hextaui.com/docs/use-merged-ref Last updated: 2026-10-27 ## Usage ```tsx import { useMergedRef } from "@/hooks/use-merged-ref" ``` ```tsx function Panel({ ref, ...props }: React.ComponentProps<"div">) { const localRef = React.useRef<HTMLDivElement>(null) const morphRef = useSizeMorph<HTMLDivElement>({ axis: "height" }) const setRef = useMergedRef(ref, localRef, morphRef) return <div ref={setRef} {...props} /> } ``` An element has one `ref`, but components often need to hand it to several places: the parent that forwarded a ref, a local ref for effects, and hooks that work through a callback ref.`useMergedRef` returns one callback that feeds all of them. ## How it works When the element attaches, every ref receives it. Object refs get `.current` set, and callback refs are called with the node. The merged callback returns a cleanup in the React 19 style. On detach it runs each callback ref's own cleanup, or calls the ref with `null` if it didn't return one, and resets object refs to `null`. ```tsx const observeRef = React.useCallback((node: HTMLDivElement | null) => { if (!node) return const observer = new ResizeObserver(onResize) observer.observe(node) return () => observer.disconnect() }, [onResize]) const setRef = useMergedRef(ref, observeRef) ``` That makes callback refs a good home for anything tied to the element's lifetime, like observers and listeners. Setup and teardown live together, and merging them with other refs keeps them working. ## Good to know ```tsx useMergedRef(ref, (node) => console.log(node)) const logRef = React.useCallback((node) => console.log(node), []) useMergedRef(ref, logRef) ``` - The merged callback changes whenever any ref changes. An inline arrow is a new ref on every render, so React detaches and reattaches the element each time. Wrap callback refs in `useCallback`. - `undefined` and `null` refs are skipped, so you can pass optional props straight in. - For one forwarded ref plus a local object ref, [useComposedRef](https://hextaui.com/docs/use-composed-ref) is shorter. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/use-merged-ref.md ---  # usePagination > Turns a page and a page count into the list of pages and ellipses to render, keeping its length steady as the page moves. Canonical: https://hextaui.com/docs/use-pagination Last updated: 2026-10-27 ## Usage ```tsx import { usePagination } from "@/hooks/use-pagination" ``` ```tsx const { items, page, hasPrevious, hasNext } = usePagination({ page: currentPage, count: totalPages, }) items.map((item) => item.type === "ellipsis" ? ( <span key={item.position}>…</span> ) : ( <a key={item.page} href={`?page=${item.page}`}>{item.page}</a> ) ) ``` The hook only does the math. It returns the list of pages and ellipses to render and leaves the markup to you, which is how `Pagination` builds its links. Use it to build your own pager, like dots for a carousel or a page picker in a table footer. ## How it works The list always shows the first and last `boundaries` pages, and `siblings` pages on each side of the current one. An ellipsis fills any gap of two pages or more. A gap of exactly one page shows that page instead, because an ellipsis there would hide no more than it takes up. ```bash count: 20, siblings: 1, boundaries: 1 page 1 1 2 3 4 5 … 20 page 6 1 … 5 6 7 … 20 page 20 1 … 16 17 18 19 20 ``` Once there are enough pages, the list always has `2 × boundaries + 2 × siblings + 3` items. Near the ends, the window widens instead of shrinking. Because the length never changes, the pager keeps its width, and the next and previous buttons stay under the pointer as you click through. - `count` and `page` are clamped: a page past the end becomes the last page, and anything that isn't a finite number falls back to the default. - A `count` of 0 returns no items and a `page` of 0, so an empty table can render nothing without a special case. - `siblings` and `boundaries` go from 0 to 10. - Ellipses have a stable `position` of `start` or `end`. Use it as the React key. ## Good to know - Mark the current page with `aria-current="page"` and wrap the list in a `<nav>` with a label. - Hide ellipses from screen readers with `aria-hidden`. They carry no information that the page numbers don't. - Show page numbers with `tabular-nums` so the buttons don't change width as the digits change. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/use-pagination.md ---  # useToday > Today's date that rolls over at midnight and when the tab comes back, without a hydration mismatch. Canonical: https://hextaui.com/docs/use-today Last updated: 2026-10-27 ## Usage ```tsx import { useToday } from "@/hooks/use-today" ``` ```tsx const today = useToday() if (!today) { return <Skeleton className="h-5 w-40" /> } return <p>{format(today, "PPPP")}</p> ``` Reach for it whenever a component depends on the current date, such as highlighting today, disabling past days or counting down to a deadline. ## Why not new Date() ```tsx const today = new Date() ``` Reading the date while rendering breaks in two ways: - Hydration mismatches. The server renders in its time zone, possibly hours earlier. Near midnight, server and browser disagree on the day, and React throws away the server HTML. - Stale dates. A tab left open overnight keeps showing yesterday as today until something else re-renders it. `useToday` returns `undefined` on the server and during hydration, then the local date. It also re-renders at midnight and when the tab becomes visible again, because timers in background tabs can be paused and miss midnight. ## Good to know - The returned `Date` is midnight in local time, so comparing it with `<` or `>` compares days, not times. - The same `Date` object comes back until the day changes, so it's safe to use in effect dependencies. - Plan for the `undefined` render. A skeleton, or rendering without date-based limits, both work. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/use-today.md ---  # Hairline > Borders and rings exactly one device pixel wide on every screen, through one variable the whole theme reads. Canonical: https://hextaui.com/docs/hairline Last updated: 2026-10-27 ## Usage ```tsx <div className="border" /> <ul className="divide-y" /> <div className="border-2 sm:border-hairline" /> <button className="inset-ring-(length:--hairline) inset-ring-border" /> <hr className="h-(--hairline) border-0 bg-border" /> ``` You rarely need to reach for it. The theme makes it the default border width, so `border`, `border-t` and `divide-y` all draw hairlines. Use the variable directly where Tailwind has no default, like rings, outlines and lines drawn with a background. ## Why hairlines A CSS pixel covers two or three physical pixels on most screens, so a `1px` border is really two or three device pixels thick. `--hairline` divides by the display's pixel ratio so every line is exactly one device pixel, the way native apps draw separators. On a standard display it stays 1px. | Pixel ratio | Description | | --- | --- | | `1×` | 1px | | `1.5×` | 0.667px | | `2×` | 0.5px | | `3×` | 0.333px | | `4×` | 0.25px | ## Good to know - HextaUI components draw edges with `inset-ring-(length:--hairline)` rather than borders. An inset ring takes no layout space, so a state that changes the ring's color or width never shifts the content. - Hairlines are lighter on the page, so a border color tuned for 1px lines may look faint. The theme's `--border` is tuned for hairlines. - Use `border-2` or wider for emphasis, like a selected card. Those stay in CSS pixels. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/hairline.md ---  # Hotkey > Parse, label, announce and match keyboard shortcuts, with ⌘ on Apple platforms and Ctrl everywhere else. Canonical: https://hextaui.com/docs/hotkey Last updated: 2026-10-27 ## Usage ```tsx import { formatHotkey, matchesHotkey, parseHotkey, useIsApple, } from "@/lib/hotkey" ``` ```tsx function SaveShortcut({ onSave }: { onSave: () => void }) { const apple = useIsApple() React.useEffect(() => { const onKeyDown = (event: KeyboardEvent) => { if (matchesHotkey(event, "mod+s")) { event.preventDefault() onSave() } } window.addEventListener("keydown", onKeyDown) return () => window.removeEventListener("keydown", onKeyDown) }, [onSave]) return <span>Save {formatHotkey("mod+s", apple)}</span> } ``` Write each shortcut once, as a string, and use the same string to display it, announce it and match it. `mod` means ⌘ on Apple platforms and Ctrl everywhere else. That's almost always what you want, since Ctrl+K on a Mac and ⌘K on Windows both feel wrong. ## Syntax ```bash "mod+k" ⌘K on Apple platforms, Ctrl+K elsewhere "shift+mod+p" modifiers in any order "cmd+option+esc" aliases: cmd, command, option, opt, control, esc, return "alt+up" up, down, left and right for the arrow keys "mod++" a literal plus key "g g" a sequence of two chords, separated by a space ``` Keys are separated by `+` and are case-insensitive. Named keys use the lowercase `KeyboardEvent.key` value, like `enter`, `tab`, `pageup` or `f5`. Use `space` for the space bar. ## Parsing ```tsx parseHotkey("mod+shift+k") // [["shift", "mod", "k"]] parseHotkey("cmd+opt+esc") // [["alt", "meta", "escape"]] parseHotkey("g i") // [["g"], ["i"]] ``` `parseHotkey` returns one array per chord, with aliases resolved and modifiers sorted into Apple's order: Control, Option, Shift, Command. Every label built from it reads in the order people expect to see it. ## Labels ```tsx formatHotkey("mod+shift+k", true) // "⇧⌘K" formatHotkey("mod+shift+k", false) // "Shift+Ctrl+K" keyLabel("enter", true) // "↵" spokenKey("mod", true) // "Command" spokenKey("mod", false) // "Control" ``` Apple platforms use symbols with no separator, the way menus show them. Windows and Linux use words joined by `+`. Symbols are hard to read aloud, so `spokenKey` gives the name a screen reader should announce instead. `<Kbd keys>` shows the symbol and puts the spoken name in visually hidden text. `useIsApple()` picks the platform. It returns `true` on the server and during hydration, then the real answer, so a Windows visitor briefly sees ⌘ before Ctrl instead of getting a hydration error. ## Matching ### Shortcut listener `matchesHotkey` checks a keydown event against a hotkey. Modifiers must match exactly, so `mod+b` doesn't fire for `mod+shift+b`. - Letters and digits also match by physical key, so `alt+k` works on a Mac, where Option+K types `˚`. - Shifted letters match: `shift+k` matches the `K` that Shift produces. - It matches one chord. For sequences like `g i`, track the previous chord yourself. - Skip shortcuts without modifiers while the focus is in a text field, so typing a letter never triggers a command. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/hotkey.md ---  # Motion > The easing curves, durations and reduced-motion check every component animates with, plus hooks for size morphs and sliding highlights. Canonical: https://hextaui.com/docs/motion Last updated: 2026-10-27 ## Principles Every HextaUI component moves with the same few curves and durations, so the library feels like one thing. - Ease out for things that respond to you. Elements entering, expanding or following a click start fast and settle, so the interface feels immediate. - Short and interruptible. Most motion is 150 to 300ms. Anything that can be reversed starts from where it is now rather than restarting. - Reduced motion is a second design, not an off switch. Movement turns into instant changes or plain fades, and state stays readable. ## Easing The theme defines the curves as Tailwind easing utilities, and `lib/motion` exports the same values for the Web Animations API. | Class | Description | | --- | --- | | `ease-out-quint` | easeOut in JS. The default for movement: popovers, highlights, size changes. | | `ease-out-cubic` | A softer ease out for color and shadow changes on hover and focus. | | `ease-in-out-quart` | easeInOut in JS. For movement between two resting states that nobody triggered directly. | | `ease-spring` | easeSpring in JS. A spring with a small overshoot, written as linear(), for things that land, like a toggle's thumb. | | `ease-drawer` | The iOS sheet curve for drawers and sheets that slide in from an edge. | ```tsx <div className="transition-transform duration-300 ease-out-quint motion-reduce:transition-none" /> <div className="transition-colors duration-150 ease-out-cubic" /> <aside className="transition-transform duration-500 ease-drawer" /> ``` ## Durations ```tsx import { duration, easeOut, prefersReducedMotion } from "@/lib/motion" element.animate( [{ opacity: 0, translate: "0 4px" }, { opacity: 1, translate: "0 0" }], { duration: prefersReducedMotion() ? 0 : duration.enter, easing: easeOut, } ) ``` | duration. | Description | | --- | --- | | `press: 100` | Pressed state going down. | | `release: 200` | Coming back up after a press. | | `hover: 150` | Hover and focus feedback. | | `enter: 200` | Elements appearing. | | `exit: 150` | Elements leaving. Exits are faster than entrances, so they never hold anything up. | | `morph: 300` | Size and position changes. | `prefersReducedMotion()` reads the media query at call time. Check it when an animation starts rather than once on mount, so changing the system setting applies right away. It returns `true` on the server. ## Size morphs ```tsx const morphRef = useSizeMorph<HTMLButtonElement>({ axis: "width" }) <button ref={morphRef} className="overflow-hidden whitespace-nowrap"> {copied ? "Copied to clipboard" : "Copy"} </button> ``` - Any DOM change inside the element triggers a morph, whether text, children or icons. Size changes from outside, like a resize, don't, so the element follows its container without lag. - A change mid-morph continues from the current size. While it runs, the element has `data-morphing`, which you can use to clip overflow or pause other transitions. - Keep the element at its natural size: no fixed width or height on the animated axis. Add `overflow-hidden` so the new content doesn't spill out while it grows. - It returns a callback ref. Combine it with other refs using `useMergedRef`. ## Sliding highlights ```tsx const barRef = React.useRef<HTMLDivElement>(null) const highlightRef = React.useRef<HTMLSpanElement>(null) useSlidingHighlight(barRef, highlightRef, "[data-active]", "data-active") <div ref={barRef} className="relative isolate flex"> <span ref={highlightRef} aria-hidden="true" className="absolute top-0 -z-1 opacity-0 transition-all duration-300 ease-out-quint data-instant:transition-opacity data-visible:opacity-100" /> {items} </div> ``` - The highlight is sized and translated with inline styles. Give it `absolute top-0` and a transition on `transform`, `width`, `height` and `opacity`. - The hook watches the attribute you name with a `MutationObserver`, so it follows state from anywhere, including Base UI's own `data-pressed`, `data-checked` or `aria-current`. - `data-visible` is set while something matches. `data-instant` is set when the highlight should jump: on first appearance, on resize and scroll, and under reduced motion. Style it as `data-instant:transition-opacity`. - It measures with the bar's scale in mind, so it stays aligned inside a dialog that's still zooming in. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/motion.md ---  # Scroll fade > Edges of a scroll area that fade only when there's more to see, driven by the scroll position in CSS alone. Canonical: https://hextaui.com/docs/scroll-fade Last updated: 2026-10-27 ## Usage ```tsx <div className="scroll-fade h-64 overflow-y-auto">…</div> <div className="flex scroll-fade-x overflow-x-auto">…</div> ``` Add it to any element that scrolls. An edge fades only while there is more content past it, so a cut-off row signals "keep scrolling" and a list at rest keeps crisp edges. ## How it works The fade is a `mask-image`, so content dissolves into whatever is behind it. There's no overlay gradient to match to the background, and it works on images, tinted surfaces and glass. A CSS scroll-driven animation grows each edge's fade over the first and last 96px of scrolling. No JavaScript runs, and it never re-renders. - Each fade is 12% of the container, capped at 40px. - Browsers without scroll-driven animations show both fades all the time. It's a little less precise, but still reads as scrollable. - `scroll-fade-x`, `scroll-fade-s` and `scroll-fade-e` follow the writing direction, so the start fade sits on the right in right-to-left layouts. ## Good to know - The mask fades the element's own background and border too. Put the surface on a wrapper and the fade on the scrolling child, as the examples do. - A mask hides everything near the edge, including focus rings. Give the scrolling element some padding so focused items aren't faded out. - Use [Scroll area](https://hextaui.com/docs/scroll-area) instead when you also want custom scrollbars. It has its own fades, measured with JavaScript, which work in every browser. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/scroll-fade.md ---  # Shimmer > A band of light that sweeps across text for in-progress states, tinted from the text color and still under reduced motion. Canonical: https://hextaui.com/docs/shimmer Last updated: 2026-10-27 ## Usage ```tsx <p className="shimmer text-muted-foreground">Generating response…</p> ``` Use it on short text that describes work in progress, like an assistant thinking, a file processing or a step that's running. The moving highlight says "still working" without a spinner taking up space beside the words. ## How it works The text is painted with a gradient through `background-clip: text`, and a lighter band slides across it. The band is derived from the text's own color, so it suits muted, foreground or colored text without configuration, and it brightens in dark mode, where a lighter band reads better. - Under reduced motion the gradient is removed entirely and the text renders in its normal color. - In right-to-left layouts the sweep reverses, so it still travels in reading direction. - The text stays real text: selectable, searchable and read normally by screen readers. ## Good to know - Keep it to a line or two. A shimmering paragraph is tiring to read. - Put the text in a `role="status"` region when it changes, so the new step is announced. The shimmer itself is decoration. - For placeholder blocks rather than text, use [Skeleton](https://hextaui.com/docs/skeleton), which shimmers surfaces with the theme's `animate-shimmer`. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/docs/shimmer.md ---  # Address Form > A shipping or billing address form that changes with the country. Handles address search, postal codes, saved addresses and error summaries. Canonical: https://hextaui.com/blocks/address-form Last updated: 2026-10-22 ## Overview Address Form asks for an address the way the shopper’s country writes it. A US address gets City, State and ZIP code on one row, the UK gets Town or city and Postcode with no state, Germany puts the postal code before the city, and Japan starts with the postal code and prefecture. Sixteen countries have their own format with labels, required fields, region lists and postal rules, and every other country gets a plain fallback. Fewer fields come first. Full name is one field, Company and Apartment sit behind small links, and the phone is optional with the reason under it. Every input has the right autocomplete token with a shipping or billing prefix, the right keyboard on phones and a name, so browser autofill fills the whole form at once, including the hidden apartment field. Errors show when you leave a field, then update as you type until it’s fixed, and they say what’s wrong: “Enter a 5-digit ZIP code”, “Enter a postcode like SW1A 1AA”. validate() lists every problem in a summary at the top with links to the fields and moves focus there. Switching country keeps what still fits, clears regions that don’t, and re-checks only fields you’ve already visited, while the form’s height animates to the new layout. Pass onSearchAddress and onResolveAddress to suggest addresses as the shopper types, with Enter address manually always at the end of the list. onLookupPostalCode fills city and region from a postal code without overwriting anything typed. SavedAddresses lists a signed-in shopper’s addresses with a Default badge, and AddressSummary is the one-line Ship to row for a finished checkout step. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/address-form.md ---  # Agent Todos > The plan an agent keeps while it works, one line per step. Handles steps in progress, failed steps and plan changes mid-run. Canonical: https://hextaui.com/blocks/agent-todos Last updated: 2026-10-22 ## Overview Coding agents like Claude Code, Codex and Gemini CLI keep a written plan while they work, through tools such as TodoWrite, update_plan and write_todos. Agent Todos turns that plan into one line per step, with the step in progress spelled out (“Running the tests”) and how long each one took. Every step moves from backlog to to do, in progress, and then done, failed or cancelled. When the agent rewrites its plan, new steps highlight, removed ones collapse out and a short note says what changed. A failed step keeps its reason in view, and long runs of finished steps fold away so the current work stays on screen. AgentTodosStatus puts the current step and a count in one line above the composer, and AgentTodosReview lets people edit, reorder, add and remove steps before anything runs, then start with ⌘↵. Adapters read each agent’s tool format, including input that is still streaming, and Tool Calls can show the work inside any step. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/agent-todos.md ---  # API keys > The API keys page of an AI product. Handles a secret shown only once, revoke with undo and rotation with a grace period. Canonical: https://hextaui.com/blocks/api-keys Last updated: 2026-10-22 ## Overview OpenAI, Anthropic and Vercel all ship the same API keys page: a list of keys you can only see the end of, a dialog to make a new one, and a single chance to copy the secret. API keys is that page as one block that drops into any Settings section. It handles the parts that go wrong: secrets lost because a dialog closed, keys revoked by accident, and lists that jump when something leaves. Each row shows the key’s name, the masked secret like hx_live_…a3F9, its permissions, the project, when it was made and when it was last used, or Never used. Keys that expire within a week get a warning badge and expired ones say so. Pass usage and a small chart of daily requests sits beside the key on wider screens. Create key opens a dialog with a name, a project, permissions (all, read only, or restricted to the resources you tick) and an expiry of 30 days, 90 days, never or a date you pick. Then the same dialog turns into the reveal: the full key in a monospace box, a Copy button that confirms with a check, and a box to tick before Done works. Try to close it before copying and it stays open with a warning and a Close anyway button. The tab asks before closing too. Revoking asks first, naming the key. Then the row collapses away and a toast offers Undo for five seconds, and onRevoke only runs once that window closes, so Undo needs nothing from your server. Leaving the page or creating another key sends any waiting revokes right away. Rotate key swaps in a new secret and can keep the old one working for an hour, a day or a week. Rename in place with F2 or a double-click, Enter to save and Escape to cancel. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/api-keys.md ---  # Appearance > The Appearance section of an AI product’s settings. Theme, density and text sizes stay a draft until people save. Canonical: https://hextaui.com/blocks/appearance Last updated: 2026-10-22 ## Overview Appearance groups everything about how the app looks into one section. Theme cards show a small window in each theme, drawn in the accent you've picked, so the choice is clear before you save. System follows the device and says which one it is right now. High contrast strengthens edges and text and keeps backgrounds neutral, so the tint slider turns off while it's picked. The accent hue is a real color track with eight quick picks under it, and the readout names the color, like Blue 250°. Background tint mixes that accent into the surfaces. Density and chat font cards show a sample of each option, and the two text sizes are steppers with limits. Reduce motion and Reduce transparency say when the device already asks for either. Everything is a draft until it's saved. The save bar from Settings rises as soon as something differs, Discard brings back the saved look, and Reset puts every option back to its default as a draft you can still discard. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/appearance.md ---  # Artifact > The panel beside an AI chat that shows what the model made. Handles content still streaming, a sandboxed preview and versions you can restore. Canonical: https://hextaui.com/blocks/artifact Last updated: 2026-10-22 ## Overview When a model makes something worth keeping, like a web page, a document or a file, it belongs beside the chat instead of inside it. Artifact Workspace puts your chat and a panel side by side. The panel opens on its own when an artifact starts streaming, slides in while the chat makes room, and can be resized, expanded to take the whole width or dragged closed. On phones it becomes a bottom sheet that only opens when you tap a card, so reading the chat is never interrupted. While the model writes, the panel shows highlighted code that follows new lines, with a Jump to latest button if you scroll up. Web pages and SVGs switch to their preview when writing finishes, never mid-stream, and the preview keeps showing the last finished version until then. Documents render as Markdown while they stream. Previews run in a sandboxed iframe with no access to your site, swap in only after the new version has loaded so there is no white flash, and report runtime errors with a Fix it action you can send back to the model. Small changes don’t rewrite the file. An update can send edits, each a find and replace applied in order to the last finished version, like Claude’s artifacts. The code stays on screen and scrolls to each edit, removed lines are struck through and fold away, new text types in with a green tint, and the rest of the file stays still. The card says Editing with the number of changes. An edit whose text isn’t found, or is found more than once, fails that version with a message saying which edit and why, and the last good version stays current. Use edits for local changes and the whole content when most of the file or its structure changes. Every update is a new version. The header lists them with what changed, Show changes compares a version with the one before it line by line with the same diff view as Diff Review, and older versions can be restored without deleting anything. The added and removed counts beside the toggle and on the card are the rows the diff shows. A new version always comes to the front. Cards in the chat show the version their message made, so clicking an old card opens that version. getArtifactsFromMessages builds all of this from AI SDK tool calls, and the panel, code view and preview also work on their own. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/artifact.md ---  # Billing > The plan and usage page of an AI product. Handles credits running out mid-cycle, plan changes with proration and card errors. Canonical: https://hextaui.com/blocks/billing Last updated: 2026-10-22 ## Overview Billing is the Plan & usage section of an AI product’s settings. It drops into a SettingsShell section and covers what people come to that page for: how much they’ve used, whether it will last, what they pay, and how to change it. The usage meter fills by model, with a lighter extension showing where the cycle will likely end at the pace of the last 7 days. When that runs past the included credits, a quiet note says when: “At this pace you’ll run out around Oct 24, 4 days before your credits reset”, with ways to turn on extra usage or see plans. Below it, a daily bar chart built on Chart covers the whole cycle: past days, today in full strength, the rest of the cycle as faint projected bars at your recent pace, and a dashed line for the even pace that would last the cycle. Hover or focus it and use the arrow keys to read any day. Limits are a draft, like every other settings section. Drag the alert threshold or turn on extra usage and the markers move on the meters straight away, the extra usage meter slides in, and the save bar rises. A limit lower than what was already spent this cycle is refused with the amount. Upgrades show the exact proration before anything is charged: the new plan for the days left, the unused days of the current one, and “You’ll pay $13.33 today”. Downgrades wait until the end of the period and list what goes away. Canceling is one honest confirmation with no offers, the plan stays on until the period ends, and Keep Pro undoes it until then. The card form formats numbers as you type without moving the cursor, checks them with Luhn, detects the brand, and validates the expiry and security code. Invoices have status badges, Pay now for failed ones, and download as real PDF files. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/billing.md ---  # Cart > Add to bag button, bag icon with a live count and a cart drawer or page. Handles optimistic quantities with rollback, undo on remove and free shipping progress. Canonical: https://hextaui.com/blocks/cart Last updated: 2026-10-22 ## Overview Cart is the add-to-bag flow of a store: AddToCartButton on the product page, CartTrigger in the header, and CartDrawer, which slides in from the right on desktop and up from the bottom on phones. CartPanel shows the same cart as a full page. Every change applies at once. Pressing plus updates the quantity, line total and subtotal straight away, and the request runs behind it. Quick presses are merged into one request for the final quantity. If your callback throws, the line goes back to the last confirmed quantity and shows your message, such as “Only 2 left in Sand / Large”. The same logic is exported as useOptimisticCart for your own layouts. Removing a line collapses it into a “Removed Ring Vase · Undo” row for five seconds, and the lines below slide up. Undo puts the line back where it was. Lines can also show that their price changed since they were added, or that they sold out, which blocks checkout until they are removed. The free shipping bar shows how much is left to spend and plays one short moment when the threshold is crossed. AddToCartButton keeps its width while it moves from the label to a spinner (only after 300ms) to a drawn check, and the bag badge rolls only the digit that changed. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/cart.md ---  # Chat Sidebar > The sidebar of a chat app, with pinned chats, projects and recents. Handles rename in place, delete with undo and chats still replying. Canonical: https://hextaui.com/blocks/chat-sidebar Last updated: 2026-10-22 ## Overview ChatGPT, Claude, Perplexity and Grok all settled on the same sidebar: start a chat or search from the top, keep a few chats pinned, group work into projects, and scroll back through everything else by day. Chat Sidebar is that sidebar, built on the HextaUI Sidebar’s inset variant, so the conversation sits in its own rounded panel inside the frame. It collapses to an icon rail on desktop, and on phones it slides in to fill the screen and slides away as soon as you pick a chat. The header holds your logo, a search button and the collapse button. New chat sits below with its shortcut always visible, followed by any links you pass, such as Images, Library or Plugins. Projects are collapsible folders, each with its own icon, and their chats sit indented inside them rather than in the history. Recents group into Today, Yesterday, Previous 7 days, Previous 30 days and then by month, and render in pages as you scroll, so thousands of chats open instantly. Every row has a menu on hover and the same menu on right-click: pin, rename, move to a project and delete. Rename happens in place with double-click or F2. Delete hides the chat at once and offers Undo for five seconds before calling onDelete. A chat that is replying shows a spinner and one that finished elsewhere shows a dot; both step aside for the menu button on hover. The account menu opens upward with your name and email on top of the items you pass in. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/chat-sidebar.md ---  # Chat Thread > The conversation view of an AI chat. Handles replies that stream, edit and retry, and versions of a reply you can switch between. Canonical: https://hextaui.com/blocks/chat-thread Last updated: 2026-10-22 ## Overview Chat Thread is the conversation around the composer: your messages, the model’s replies, and what you can do with them. It starts with your empty state and the composer centered, then docks the composer at the bottom once there are messages, without remounting it, so focus and draft text stay put. The message you just sent moves to the top while its answer streams underneath, and the view follows new text until you scroll away. A rail of checkpoints on the right lets you jump between your messages, with a preview on hover. Older history loads from the top without the view moving. Hover a message to copy, edit or try again. Edits and retries become versions you can switch between, and nothing is lost. Failed replies offer Try again, stopped replies say so, and thumbs up or down are one click. Inside each reply, Reasoning, ToolCalls and Markdown from the other blocks slot straight in. Checkpoints before your messages are restore points. Restore says exactly what goes, such as “Removes this message and 3 later messages, and reverts 3 files”, dims those messages while you decide, and lets you keep your code with Conversation only. The later messages fold away, your message goes back into the composer to edit, and a toast offers Undo. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/chat-thread.md ---  # Checkout > A one-page checkout with contact, delivery and payment beside a live order summary. Handles changed totals, sold-out items and unknown outcomes. Canonical: https://hextaui.com/blocks/checkout Last updated: 2026-10-22 ## Overview Checkout puts contact, delivery and payment on one page, with the order summary beside it on wide screens and folded above it on phones. Each step opens in place and turns into a short summary row when it’s done, so a finished checkout reads like a receipt: “Contact maya@example.com”, “Ship to 12 Mission St, San Francisco, CA 94110”, “Method Standard · Arrives Oct 26 – 28 · Free”. Change on any row reopens that step and moves focus to it. Signed-in customers skip contact and start at delivery with their default saved address. Pass the cart and three callbacks: onGetRates(address), onEstimateTax(address) and onPlaceOrder(draft, payment). Rates and taxes load as soon as the address is complete, with a short pause while someone is typing, and the previous request is aborted through its signal when the address changes. The cheapest rate is picked for you, and the summary shows “Calculating…” rather than a stale number while new prices load. onPlaceOrder gets a draft with the email, lines, addresses, chosen rate and the exact total the shopper saw, plus the payment request with a fresh idempotency key. Return succeeded with the order, declined with a code, requires_action for 3-D Secure, or changed when the server’s prices differ. A changed result never charges: the summary updates, a notice lists each change in plain words (“Ring vase is now $74, was $68.”) with the old total struck through, and the shopper presses Pay again at the new amount. The page also handles the slow and strange cases. Pay can’t run twice, and the Change buttons lock while an order is placing. If onPlaceOrder doesn’t answer within 20 seconds, the page says it’s checking the status and polls onCheckStatus with the same idempotency key instead of offering to pay again. An item that sells out mid-checkout is taken out of the total and flagged until the shopper removes it or continues without it, and pressing Pay with gaps lists every problem in one linked summary. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/checkout.md ---  # Code Block > Code blocks for AI answers. Highlighting keeps up with streaming, diffs can be accepted or rejected, and commands run in a terminal. Canonical: https://hextaui.com/blocks/code-block Last updated: 2026-10-22 ## Overview Code in an AI answer arrives a few characters at a time, often as a diff someone has to approve. Code Block highlights while it streams, follows new lines unless the reader has scrolled up, and keeps copy, download and wrap out of the way until the code is complete. Highlighting uses Shiki with GitHub’s light and dark themes, loaded per language on demand. Only new lines are tokenized as text arrives, so long files stay fast, and both themes render at once so switching color scheme never flashes. Blocks longer than 16 lines fold behind “Show all”. Pass a unified diff and you get old and new line numbers, a change count and tinted rows; copying gives the new version, not the diff. Add a review and the reader can accept or reject the change, with ⌘↵ and ⌘⌫ while the block has focus. CodeFence plugs the same block into Streamdown, and CodeTerminal shows commands with their output and exit code. CodeTerminal reads the ANSI codes that test runners and package managers print: bold, dim, italic, underline, the 16 colours mapped to theme tokens that read well in light and dark, 256 colours and truecolor. Carriage returns overwrite the line, so progress bars and spinners settle on their last state, OSC 8 links become real links, and a code split across two chunks never flashes on screen. Copy gives plain text, and long output folds behind “Show all”. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/code-block.md ---  # Commerce Dashboard > A complete store admin built from the HextaUI commerce blocks. Handles refunds, fulfillment and stock edits that update every page at once. Canonical: https://hextaui.com/blocks/commerce-dashboard Last updated: 2026-10-22 ## Overview Commerce Dashboard is a whole store admin for the Halden home goods shop, made from the other commerce blocks. Home and Analytics are Sales Overview, Orders is Orders Table, an order opens in Order Detail with the Refund sheet, Products opens Product Editor, Inventory is Inventory Table, and Discounts opens Discount Builder. The dashboard adds only the glue: a sidebar, a top bar with search and notifications, routing, one shared store, and small Products, Customers and Discounts lists. Everything reads from one store, so a change in one place shows up everywhere. Refund an item and the order’s payment pill, its timeline, the customer’s total spent and the stock you chose to restock all change together. Fulfill an order and its pill in the orders table flips, the unfulfilled count in the sidebar drops and committed stock goes down. Rename a product and the list, the inventory table and the search palette pick it up. Routing lives in the block. Pages are hash URLs like #/orders/order-1042, so Back and Forward work and links open in a new tab, and you can swap in Next.js routes through the router prop. Leaving a page with unsaved product, stock or discount edits is blocked with a message, including with the browser’s Back button. Pages cross-fade in 150 ms, and not at all with reduced motion. The sidebar follows the new Shopify admin. The store switcher, search and a notifications bell sit at the top. Orders, Products, Customers and Analytics open their sub-pages with a separate chevron, the current section opens on its own, and your open sections are remembered. Sales channels and pinned apps sit below, with an amber dot when a channel fails to sync. The footer holds one card at a time (a setup checklist first, then an announcement you can dismiss), Help & support, Settings and your account menu with theme and language. ⌘B or the rail collapses it to icons, where sections open as flyouts and counts become dots. On a phone it's a sheet that closes when you pick a page, and only the page content scrolls. Press ⌘K or Ctrl+K to jump to a page, an order by number or customer, a product, or a discount code, ⌘1 to ⌘9 to switch stores, and ? for the shortcuts list. Pages that don't have their own block yet, like Drafts or Purchase orders, show a short empty state with what they're for, and Collections and Segments list your real data. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/commerce-dashboard.md ---  # Diff Review > A review of an agent’s file edits before they land. Handles accept or reject per change, comments back to the agent and edits still streaming. Canonical: https://hextaui.com/blocks/diff-review Last updated: 2026-10-22 ## Overview Coding agents change several files at once, and people need to keep some of it and throw the rest away. Diff Review puts every edit in one scrolling list with a file tree beside it, so you can accept or reject a single change, a whole file or everything, from the mouse or the keyboard. DiffSummary is the “Edited 4 files +120 −34” card for the chat, with the same actions on each file. Each decision touches exactly one change. A decided change folds down to a one-line stub with its result, Show and Undo, and a file folds away once every change in it is decided. Bulk actions say how many changes they cover, and every decision, including Accept all and Reject all, can be undone with U or ⌘Z. “Next” always means the next change you haven’t decided yet. The counts and the progress bar come from what is still pending, so the review ends with a clear “All reviewed”. Hover a line and press + in the gutter, or focus a line and press Enter or C, to comment on it. Drag or Shift-click line numbers, or use Shift+↑↓, to comment on a range. The composer opens as a small popover under the line, and a sent comment stays on the line as a thread you can edit, delete with undo, or collapse, with a count in the gutter. Removed lines are reported on the old side and added or unchanged lines on the new side, so the line numbers always match the file. Pass a unified diff, or the content before and after and let the block compute the diff. With full content you can show the unchanged lines between changes, 20 at a time upward or downward, or all at once when fewer than 20 are hidden. Removed lines carry a fine striped bar in the gutter and added lines a solid one, so the difference never depends on color. Lines are highlighted with Shiki like Code Block, and changed words inside a line are marked when the two lines are similar enough for that to help. The layout switches to split view when there is room, which is at least 900px by default. Files that are still streaming show live and can’t be decided yet. Files that changed on disk can be rejected but not accepted. Diffs over 400 changed lines wait behind Load diff, and their file-level actions keep working. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/diff-review.md ---  # Discount Builder > A discount builder where the offer is one editable sentence, with a live checkout preview. Handles code checks, drafts and schedules. Canonical: https://hextaui.com/blocks/discount-builder Last updated: 2026-10-22 ## Overview Discount Builder is the page a merchant uses to create or edit a discount. A new discount opens with a short type dialog: amount off products, amount off order, buy X get Y or free shipping. After that the offer is a sentence the merchant edits in place: “Customers get [15%] off [Ring Vase and Glass Carafe]”. Each underlined part is a real control with a label, so screen readers hear “Percentage off, 15” rather than a sentence of buttons. Everything optional sits in a Rules card as collapsed rows: Minimum purchase, Customers, Usage limits, Combines with and Schedule. Each row shows its current value, so a merchant can read the whole setup without opening anything, and each panel explains its setting with an example. Schedules start now by default and offer presets for 7 days, 30 days and the end of the month, in the store’s time zone. The rail is a preview, not a list of settings. It shows the offer as one sentence and a sample checkout built from your products, with the discount applied and what the customer saves. A Qualifies / Doesn’t toggle swaps to a cart just under the minimum and shows the same message a storefront would, such as “Add $10.00 more to use SUMMER15”. Risky settings, like 100% off with no limit, show up as warnings under it. Data goes in, async callbacks come out. onSave gets a cleaned Discount and the intent (draft or live); return field errors to show them on the sentence or the rule rows, or throw to show the message in the save bar. Errors appear when a field is left, never while typing. New discounts save from the header (Save draft and Create discount). Existing ones use the shared IslandBar, which appears only when there are unsaved changes. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/discount-builder.md ---  # HextaAI > A complete AI chat app built from the HextaUI AI blocks. Handles streaming, tool approvals and plan review end to end on AI SDK message parts. Canonical: https://hextaui.com/blocks/hexta-ai Last updated: 2026-10-22 ## Overview HextaAI is a complete AI chat app made from every HextaUI AI block. Chat Sidebar holds the history, Chat Thread holds the conversation, Prompt Input is the composer, and each reply is drawn from its parts: Thinking for reasoning, Tool Calls for what the agent did, Agent Todos for its plan, Code Block for diffs and terminals, and Streaming Markdown for the answer. Artifact opens web pages, documents and files the model makes in a panel beside the chat, with versions, and small changes are typed into the open file instead of rewriting it. Voice Mode opens from the composer and drops the conversation into the chat when you hang up. The core is HextaMessageParts. It takes the same message parts the AI SDK’s useChat returns, groups neighbouring reasoning and tool calls, keeps one live plan at the top of the reply, and renders text with citations linked to the sources the model found. Reads, edits, writes, searches, web fetches and shell commands each get a fitting view, and you can add renderers for your own tools. The demo runs on ScriptedChats, a small engine that streams realistic parts offline. Try a suggestion: make a pricing page and watch it open beside the chat, research a question and watch sources come in, ask for a feature and review the plan before it runs, approve a test run that fails and gets fixed, or ask for an explanation with code and tables. Stop, regenerate, edit and switch chats while replies keep streaming in the background, then open voice mode and talk. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/hexta-ai.md ---  # Inventory > A stock table where merchants edit quantities in place and save adjustments. Handles live orders, edits from another device and oversold or untracked stock. Canonical: https://hextaui.com/blocks/inventory Last updated: 2026-10-22 ## Overview Inventory is the stock table for one location. Each row is a variant with its thumbnail, title and SKU. The columns follow Shopify: Unavailable, Committed, Available, On hand and Incoming. On hand is always Available plus Committed plus Unavailable, so editing one of them moves the other by the same amount. Click a quantity, press Enter or start typing to open the editor. Adjust by adds or removes stock and Set to enters a count, with a live preview such as 42 → 47. The arrow keys step by 1, or by 10 with Shift. Enter keeps the change in a draft and moves down a row, and Escape cancels. Edited cells get a dot and show their delta, and a save bar collects the batch with one reason, such as Received or Cycle count. Saving sends adjustments, not overwrites. Each one carries its delta, the quantity it was based on and the result, so an order placed while you were typing isn’t lost. A row the server rejects stays in the draft with its message, such as “Quantity changed to 40 by another device”, and Reapply sends it again on top of the new quantity. When new items arrive, changed numbers roll digit by digit and flash briefly. Rows don’t re-sort while you’re working in the table. The toolbar has search by title or SKU, Low stock, Out of stock and Incoming filters, sorting by Available, and bulk Set to 0 or Adjust by for selected rows. Loading, an empty location, no results, untracked variants, oversold stock and an all-locations read-only view are covered too, and every row has its adjustment history in a sheet. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/inventory.md ---  # Markdown > Markdown rendering for AI answers. Handles streaming without half-typed syntax, tables you can copy and inline citations. Canonical: https://hextaui.com/blocks/markdown Last updated: 2026-10-22 ## Overview Models answer in Markdown, and they write it a token at a time. A plain renderer flashes raw asterisks, half-built tables and unclosed code fences while it streams. Markdown completes unfinished syntax as it goes and paces the text like the Streaming block, so formatting appears in place. Each element is built from the rest of HextaUI. Code fences become Code Blocks, GitHub callouts like [!NOTE] use Alert, task lists use read-only Checkboxes, and tables scroll sideways with a menu to copy them as Markdown or CSV. Pass sources and [1] becomes a citation chip, while marks inside code are left alone. Headings get ids from their text, with an optional link icon to share them. Images load lazily with a placeholder and caption, footnotes link back to their mark, external links open in a new tab and say so, and text direction is detected per block. It works as well for READMEs and changelogs as for streamed answers. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/markdown.md ---  # Models > The Models page of an AI product’s settings. Handles the default model and effort, providers and custom servers with a connection test. Canonical: https://hextaui.com/blocks/models Last updated: 2026-10-22 ## Overview Every AI product grows a Models page: which models show up in the picker, which one new chats start with, how hard it thinks, and which small model runs the background jobs. Models is that page as one component, ModelSettings, that drops into any Settings section and saves through the same island as the rest of your settings. Default model opens a menu of the models that are on, grouped by provider, each with its context, cost and abilities. Under the picker, chips show the chosen model's context window, speed and cost, so the tradeoff is visible before anyone opens a chat. Default effort uses the effort slider from Prompt Input and knows what the default model supports. Drag past what it can do and the slider settles on its highest level, the line under it says why, and screen readers hear it too. Models that don't reason grey the slider out and explain that effort doesn't apply. The model list searches by name, provider and ability, and filters to Enabled, Reasoning, Fast or Vision. Models are grouped by provider with a count of what's on and one switch to turn a whole provider on or off. Each row shows context, a four-dot cost scale and badges for New and Preview. Pin the models you use most from a row's menu and they move to a Pinned group at the top, in the order the picker shows them. Move them with Move up and Move down, or Alt and the arrow keys, without dragging anything. Add model connects any OpenAI-compatible server, including local ones. It checks the URL, flags a model you already added and tests the connection before adding, showing how long the server took to answer or the reason it failed. The key field hides the key until you show it. Refresh asks your server for the latest catalog and shows a quiet banner such as "2 new models: Nova 3.5 and Atlas 2 Vision", with Show to filter to them. New models arrive off, so nothing changes in the picker until you choose. Task models give the explore subagent, chat titles and summaries their own model, or Auto. Nothing saves until you save: every change raises the Settings save bar, Discard puts everything back, including removed custom models, and the default model can't be turned off by accident. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/models.md ---  # Notifications > The Notifications section of an AI product’s settings. Handles a channel by event grid, quiet hours and browser permission for push. Canonical: https://hextaui.com/blocks/notifications Last updated: 2026-10-22 ## Overview Every AI product ends up with the same notifications page: a list of things that can happen, a list of places they can reach you, and a way to make it stop at night. NotificationSettings is that page as one section. It drops into a SettingsSection and uses the same draft, save bar and unsaved-changes guard as the rest of Settings. The core is a grid of events by channels. The top row turns a channel on or off for every event, the first column turns an event on or off everywhere, and the corner checkbox does all of it. Each shows a dash when only some are on. With the keyboard the grid is one tab stop: arrow keys move between checkboxes, Home and End jump along a row, and Space toggles. Screen readers hear each one as "Email for Agent finished". On a phone the grid becomes one card per event with large channel chips. Each channel has a Send test that really sends. Desktop and push show a notification banner over the page, and desktop also fires a real system notification once the browser allows it. Email opens a preview of the message in an inbox, the digest version when emails are bundled. Slack shows the message as your team sees it in the channel. Desktop reads the browser's permission. When it hasn't been asked, Allow asks; when it's blocked, it says where to change it; when the browser can't show notifications, it says so. Slack starts disconnected: its column is off, and Connect opens a dialog to pick a workspace and channel. If connecting fails, the reason shows in the dialog and nothing is lost. Quiet hours hold desktop and push alerts between two times on the days you pick, in the time zone you pick, with a line that says when the next quiet period starts or that it's quiet now. Urgent events like approvals can still come through. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/notifications.md ---  # Order Detail > The merchant’s page for one order: shipments, payment, customer and timeline. Handles partial fulfillment, holds, failed payments and cancellations. Canonical: https://hextaui.com/blocks/order-detail Last updated: 2026-10-22 ## Overview Order Detail is the page a merchant opens from the orders table: one order with everything they need to act on it. The header shows the order number, separate payment and fulfillment pills with a progress glyph (empty, half or full circle) so status never depends on color, the date and channel, the order actions and previous and next arrows. The main column splits items by what happened to them. An Unfulfilled card lists what’s left to ship, worked out as purchased minus fulfilled minus refunded. Each shipment gets its own card with carrier, tracking link, delivery status and items, and refunded items get a Refunded card. The Payment card shows the total and only the lines that matter right now (refunded and net, an authorization with its expiry, or a balance due); subtotal, discounts, shipping, tax and currency conversion sit behind Breakdown. It has Capture payment for authorizations and Send invoice for pending or failed payments. Fulfill items opens a sheet with a quantity stepper per line, capped at what’s left, a location, a tracking number that detects UPS, USPS, FedEx, DHL, Canada Post and Royal Mail from its pattern, and a Notify customer switch. Submitting closes the sheet and adds the shipment and a timeline event straight away. If onFulfill throws, both roll back and a toast offers Try again with the same choices. The timeline reads like Shopify, Linear and Stripe activity feeds: a rail with one icon per event type (status color only on the icon), a short title built from the order data (“Payment of $564.41 captured”, “Shipped with UPS” with the tracking number linked), a muted second line and a relative time with the exact date in a tooltip. Day labels stick while you scroll. Customer emails fold into the event that sent them (“Customer emailed”, with Resend in Show details), three or more same-kind events in a row collapse into one line, and older history folds behind “Show N earlier events”. Comments are cards with avatar, author, edit and delete, and attachments as chips. Filter by All, Comments or System. The composer is one line until you focus it, then shows attachments, “Only visible to staff” and Post (⌘↵), and posts optimistically with retry. The right rail keeps to what matters: notes and tags only appear when they have content or can be edited, the customer card drops repeated name and phone lines, and conversion and risk show a one-line summary with details behind Show more. Cancelled, on hold, archived and loading states, and actions a staff member isn’t allowed to take, are all handled with a reason. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/order-detail.md ---  # Order Status > Customer order confirmation, package tracking and returns. Handles split shipments, delayed or failed deliveries, final-sale items and pending payments. Canonical: https://hextaui.com/blocks/order-status Last updated: 2026-10-22 ## Overview Order Status is the page a customer lands on after checkout and comes back to while they wait. OrderConfirmation says thanks by name, shows the order number, the email the receipt went to, the expected delivery dates, what they bought and where it’s going. A check mark draws in and the details rise into place in about 800 ms, and content is readable well before that. OrderTracking follows Baymard’s six tracking essentials. Each package gets a card with a large delivery date, a progress bar that shows before anything ships, the carrier and a linked tracking number you can copy, what’s inside with thumbnails, and the full shipping history newest first. Split orders read Package 1 of 2, and items that haven’t shipped sit in their own Preparing to ship card. Problems are spelled out rather than hidden. A delayed shipment turns its step amber and says the new date, a missed delivery says when the next attempt is, a cancelled order says whether the payment was released or refunded, and a pending payment says nothing ships until it clears. ReturnRequest is a two-step return: pick items and quantities, then a reason and where the refund goes. Final-sale items, items still in transit and items past the return window stay visible but disabled, each with the reason. The refund estimate updates as you choose, including the discount and tax share and any return shipping fee, and the confirmation shows a drop-off code and the refund timeline. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/order-status.md ---  # Order Summary > The checkout sidebar with line items, discount codes and totals. Handles estimated taxes, unknown shipping and prices that changed since the cart was built. Canonical: https://hextaui.com/blocks/order-summary Last updated: 2026-10-22 ## Overview OrderSummary is the column next to a checkout form. It takes a Cart in the same shape the cart block uses and shows each line with a small thumbnail, a quantity badge on the image corner, the variant and the line total. Lists longer than five lines fold behind “Show 3 more”, so the totals stay in view. Totals come in the order shoppers expect: subtotal, one line per discount with its code as a chip, shipping, taxes and the total with its currency code, “USD $339.78”. Shipping reads “Calculated at next step” until you know it, shows a skeleton while it is being worked out and reads Free when it costs nothing. Taxes are labelled Estimated until you mark them final, with an optional basis such as “Estimated for 94110”. Store sales, discounts and free shipping add up to a “You saved” line. Discount codes sit behind an “Add discount code” link. Codes are trimmed and uppercased, the Apply button turns into a spinner and then a check, and applied codes become chips you can remove. Automatic discounts show as chips without a remove button. Throw from onApplyCode and your message appears under the field. DiscountCodeError builds the common ones: expired with the date, the amount still needed to reach a minimum, codes that can’t be combined, and codes that don’t exist. The block catches codes that are already applied and the code limit without calling you. Every amount uses Price, so when a code lands only the digits that changed roll, and nothing counts up on first render. New discount and savings lines grow in before their text fades in. If a line’s price changed since the last render, the row flashes once and keeps a note such as “Price dropped to $58”. With collapsible set, phones get a “Show order summary” bar that keeps the total visible and flashes it when it changes. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/order-summary.md ---  # Orders Table > The merchant’s orders index with saved views, filters and bulk actions. Handles partial payment and fulfillment, live orders and partial bulk failures. Canonical: https://hextaui.com/blocks/orders-table Last updated: 2026-10-22 ## Overview Orders Table is the orders index of a store admin. Each order shows its number, a relative date with the exact time on hover, the customer, channel, total, payment and fulfillment status, item count, delivery method and tags. Payment and fulfillment are separate pills, and each has a progress glyph (an empty, half or full circle) so Partially paid or Partially fulfilled reads without relying on color. Saved views sit in tabs: All, Unfulfilled, Unpaid, Open, Archived and your own. A view is a set of filters, a sort and a search. Change any of them and the tab is marked Modified, with Reset, Update view and Save as new view. Filter chips cover status, payment, fulfillment, date, channel, tag and risk. ordersQueryToSearchParams and ordersQueryFromSearchParams keep the whole query in the URL, so a link opens the same list and Back works. Selection works like a desktop list. Shift-click selects a range, the header checkbox selects the page, then Select all 48 orders selects every match. The bulk bar takes the header’s place, so nothing shifts. Mark as fulfilled, Capture payment (with a confirmation showing the amount), Add tags, Archive and Print packing slips are async. Partial failures name the orders that failed with a View link, and Archive can be undone. J and K move a focus ring, X selects, Enter opens, / searches and Esc clears. New orders that arrive while you browse slide in at the top with a soft highlight. While a row is focused or anything is selected, rows never move: a “1 new order · Show” pill waits instead. The table tells an empty store (No orders yet, Create order) from a filtered empty list (No orders match these filters, Clear filters), shows skeleton rows while loading and an error with Retry. On phones the rows become cards and the bulk bar floats at the bottom. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/orders-table.md ---  # Payment > The payment step of a checkout, with wallets, cards, PayPal and Pay in 4. Handles card validation, declines, 3-D Secure and slow banks. Canonical: https://hextaui.com/blocks/payment Last updated: 2026-10-22 ## Overview Payment is the last step of a checkout. Wrap the parts in Payment with the order total and an onPay callback, then place ExpressCheckout, PaymentMethods, BillingAddress, PayButton and PaymentStatus where they fit your layout. Payment owns the state between them, so the button label follows the chosen method: “Pay $123.45” for a card, “Continue to PayPal”, “Pay $30.87 today” for Pay in 4. The card form detects the brand from the first digits and swaps its mark only when the brand changes. It groups digits as you type, 4-6-5 for American Express, writes the expiry as MM/YY with the slash added for you, and accepts “1/27”, “0127” and pasted numbers with spaces or dashes. Each field is checked on blur or once it’s complete, then live, so an error clears the moment it’s fixed. Focus moves from number to expiry to security code only when the field before it is complete, valid and the next one is empty. onPay gets a typed request with the card details or saved card, the amount, the billing choice and a fresh idempotency key. Return nothing or { status: "succeeded" } to finish: the button shows a check, holds for 700 ms and calls onComplete. Return { status: "declined", code } and the error appears above the methods with copy written for that code, focus moves to it, the card stays filled in and “Try another card” clears it. Return { status: "requires_action" } to open the “Confirm with your bank” dialog, where renderChallenge mounts your 3-D Secure step. While a payment runs the button can’t be pressed twice, the methods are inert, leaving the page asks for confirmation, and after three seconds the status line says “Confirming with your bank…”. Saved cards that have expired show as disabled, and declineMessage gives the same copy for your own error screens. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/payment.md ---  # Price > Prices for a storefront in any currency and locale. Handles sales, ranges, unit prices, free items and prices that change with the variant. Canonical: https://hextaui.com/blocks/price Last updated: 2026-10-22 ## Overview Price is the one component every storefront block uses to show money. It takes a Money value, { amount: "48.00", currencyCode: "USD" }, and formats it with Intl for the shopper’s locale: $48.00 in the US, 48,00 € in Germany, ¥7,200 in Japan with no decimals, ₹4,000 with Indian grouping. A compare-at price higher than the price shows struck through with the saving next to it, as a percentage or an amount. Screen readers hear “Sale price $36, Regular price $48” instead of two bare numbers. A range reads “From $28” on a product card or “$28 – $78” in full, and collapses to one price when both ends match. Zero reads Free, and a missing price reads Price unavailable or your own wording. When the price changes, for example when a shopper picks a bigger size, only the digits that changed roll to their new value, with tabular figures so nothing around the price moves. Unit prices sit on their own line under the price. The money helpers behind it, money, addMoney, multiplyMoney, sumMoney, fromMinorUnits and discountPercent, work in integer minor units so 0.1 + 0.2 is 0.30, and they refuse to add two currencies together. Cart, checkout and dashboard blocks use the same helpers. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/price.md ---  # Product Card > The product tile for collection grids and rails, with swatches, quick add and a wishlist heart. Handles sold-out sizes, price ranges and failed adds. Canonical: https://hextaui.com/blocks/product-card Last updated: 2026-10-22 ## Overview Product Card is the tile you put in a collection grid, search results or a recommendations rail. It takes a Product, the same model Variant Picker uses, and shows one card per product, never one per color. The whole card is a single link on the title, while the heart, swatches and quick add stay separate buttons on top of it. Colors show as a row of small swatches, all of them reachable. On a narrow card the row scrolls sideways with the last swatch cut off and the edge faded, so shoppers can tell there are more. Hovering a swatch previews that color’s photo after a short pause and preloads it, so the crossfade never shows a blank frame. Clicking it picks the color: the price, badges and stock follow it, and the link opens the product page with ?color= set. On a mouse, hovering the card crossfades to a second photo. Quick add fits the product. A product with one variant gets an Add to bag button that keeps its width while it changes to a spinner, Added or Couldn’t add. A product with sizes shows a row of size buttons that slides up over the photo on hover or keyboard focus, with sold-out sizes crossed out. On touch screens a + button opens a bottom sheet with Variant Picker instead. A sold-out product hides quick add, shows a Sold out badge and a Notify me link. Badges come from the data: Sale −20%, Only 3 left, Pre-order and Sold out, plus your own such as New, two at most. The wishlist heart saves optimistically, pops once when saved, and rolls back with a message if your callback throws. ProductGrid lays cards out in 2, 3 or 4 columns and animates between them, and ProductCardSkeleton matches the card’s shape exactly for loading states. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/product-card.md ---  # Product Editor > The add and edit product page for a store admin. Handles unsaved changes, SKU errors from the server and someone else editing at once. Canonical: https://hextaui.com/blocks/product-editor Last updated: 2026-10-22 ## Overview Product Editor is the page a merchant uses to add or change a product: title and description, media, pricing with live profit and margin, stock per location, shipping, variants, a search result preview, and a rail for status, sales channels, type, vendor, collections and tags. It renders the page frame with breadcrumb, status badge, Preview and a menu for Duplicate, Archive and Delete, and leaves the sidebar to you. Every edit goes into one draft. The save bar slides up when the draft differs from the saved product and goes away again if you undo your edits by hand, because the check is a deep compare. ⌘S saves, Discard asks first, and Preview or the breadcrumb nudge the bar instead of leaving. A second try within a few seconds asks whether to leave without saving. onSave can return field errors, which are shown on their fields while the first one scrolls into view and gets focus, or a conflict, which turns the bar into “Leo Park changed this product 2 min ago” with Review changes and Overwrite. MediaUploader takes drops, pastes and the file picker. The first image is the large featured tile. You can drag tiles and the rest move out of the way as you go, or press Space, the arrow keys and Space again. Each upload shows its own progress. A failed one stays in place with Retry, unsupported types and files over the size limit are named in a message, and removed images come back with Undo. VariantMatrix edits up to three options as value chips that you can reorder, rename and remove, and keeps one row for every combination. Rows are grouped by an option with a summary like “$48–$96 · 12 in stock”. You can set price or stock for a whole group or a selection, delete a combination and restore it with the same SKU, filter rows, and work through hundreds of variants because collapsed groups don’t render and long groups load 25 rows at a time. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/product-editor.md ---  # Product Filters > Faceted filters for a collection page, with chips, sort and load more. Handles zero results, slow counts, long value lists and price ranges in any currency. Canonical: https://hextaui.com/blocks/product-filters Last updated: 2026-10-22 ## Overview Product Filters is the left side and the top of a collection page: a sidebar of facets, the applied filters as chips, a toolbar with the count, sort and grid size, and a Load more button with progress. On phones the same facets open in a bottom sheet. Facets are plain data, { id, label, type, values }, with list, swatch, range, boolean and rating types, so they map from Shopify, Algolia, Meilisearch or your own database. On desktop every change applies at once and a polite live region says “12 results”. Each value shows its count, and values with no matches stay visible but disabled, so shoppers never pick their way into an empty grid. Long lists show six values and “Show 3 more”, and lists of 15 or more get a search field. Price is a two-thumb slider over a histogram plus two inputs with the currency symbol. The slider applies when you let go and the inputs on blur or Enter, so typing is never interrupted. In the mobile sheet, changes are staged. The button reads “Show 24 results” and updates as you toggle, from onCount, which may be async. Stale answers are dropped, and the button turns into “No results” when nothing matches. Closing the sheet without applying throws the changes away. Every applied value becomes a chip, such as Oat or $40–$120. Removing one moves focus to the next chip, and removing the last one moves it to a target you choose. On phones the chips scroll sideways, with a count and a faded edge. When nothing matches, FilterEmpty explains why and lists the chips to remove. The pure helpers, applyFilters, computeFacetCounts and the search param pair, work on the server too. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/product-filters.md ---  # Product Gallery > The image gallery of a product page, with thumbnails, zoom and a full-screen viewer. Handles variant images, swipe on touch, broken photos, video and loading. Canonical: https://hextaui.com/blocks/product-gallery Last updated: 2026-10-22 ## Overview Product Gallery is the photo area of a product page. On desktop a thumbnail rail sits beside the main image, or a row sits under it, and a ring slides to the chosen thumbnail. Picking a thumbnail crossfades the photo in place instead of sliding through every shot in between, and it waits for the new photo to decode so the frame never flashes empty. Hover a photo with a mouse and, after a short pause, it zooms to 2× around the cursor and swaps in the higher resolution zoomSrc. Click or press Enter to open the full-screen viewer. On touch the photos swipe with native scroll snapping that follows the finger, the thumbnails stay visible and a 2 / 5 counter sits in the corner. Tap opens the viewer and double-tap opens it zoomed in on that spot. The viewer is a modal dialog. Arrows, swipes and thumbnails move between photos, and pinch, double-tap, click, the trackpad, the wheel and the + and − keys zoom and pan with soft edges. Swipe down to close, or press Escape, which first resets the zoom. Focus returns to the chosen thumbnail. With reduced motion, zoom and slide changes happen without animation. Pass activeId to drive it from a variant picker: when it changes the gallery crossfades to that photo and scrolls the thumbnail into view. No photos shows a quiet placeholder, one photo drops the thumbnails and counter, a broken URL becomes a placeholder in the same frame, long sets scroll with a faded edge, and videos show their poster with a play button and never autoplay. ProductGallerySkeleton matches the layout while media loads. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/product-gallery.md ---  # Product Search > A storefront search field with live suggestions, categories and product results. Handles typos, slow or failing searches, recent searches and keyboard-only use. Canonical: https://hextaui.com/blocks/product-search Last updated: 2026-10-22 ## Overview Product Search is the search field in a store header. On a desktop it opens a dropdown under the field, and on a phone a full-screen sheet with the keyboard up. Before anything is typed it shows recent searches, trending searches and a row of popular products. As the shopper types, it shows up to eight query suggestions with the predicted part in bold, category matches such as “linen in Bedding”, a few products with a thumbnail and price, and a final “Search for” row. Arrowing onto a suggestion copies it into the field so it can be edited, Escape puts back what was typed, and Tab completes the suggestion. onSearch(query, { signal }) is called after a short debounce. Older requests are aborted, answers are cached so backspacing is instant, and the previous results stay on screen while the next ones load. The spinner only appears when a search takes longer than 150ms. A failed search shows its error message with a Try again row, and a search with no results offers “Did you mean” and popular categories. Recent searches are kept in localStorage under recentStorageKey, or controlled with recent and onRecentChange. SearchResultsHeader is the matching heading for a results page, “Results for “vase” (4)”, with a Did you mean line. The fuzzy helpers in search.ts, fuzzySearch, completeQuery and correctQuery, power the demo and work for small catalogs on their own. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/product-search.md ---  # Profile > The Profile section of an AI product’s settings. Handles photo cropping, a username checked as you type and email changes confirmed by code. Canonical: https://hextaui.com/blocks/profile Last updated: 2026-10-22 ## Overview ProfileSettings is the Profile page from a product like Claude or Cursor, built to drop into any SettingsShell section. Give it the saved profile and an onSave, and it handles the rest: a draft that only saves when you say so, field errors from your checks or your server, and the floating save bar from Settings with ⌘S. At the top, a card shows how others see your profile and changes as you type: photo, name, handle, bio and links. Turn off Show my profile and the card dims and says only you can see it. Copy link puts the profile URL on the clipboard. Pick a photo, or drop one on the row, and it opens in a crop dialog. Drag to move it, zoom with the slider, the wheel or a trackpad pinch, and the photo is cropped to a square in the browser before it reaches onSave as a data URL. Files of the wrong type, too large or under 128 pixels are refused in the row with the reason. The username is checked as you type, without slowing typing. Checks wait 350ms after the last key, stale checks are cancelled through an AbortSignal, and names you already checked answer instantly. A taken name shows your suggestions as one-tap fixes. If you save before a check finishes, the save waits for it. Email isn't part of the draft. Change opens a two-step dialog: enter the new address, then the 6-digit code sent to it, which checks itself when the last digit goes in. A wrong code shakes and clears, Resend unlocks after 30 seconds, and the row updates once the code is confirmed. An unverified address shows Resend link. Links take whatever people paste: github.com/you, a full URL or a www address. Known sites get their icon, anything else its first letter. On save they're normalized to https URLs and empty ones are dropped. Addresses that aren't links or repeat another are marked one by one. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/profile.md ---  # Prompt Input > A chat composer that grows as you type. Handles file uploads, @ and / menus at the caret and messages typed while a reply streams. Canonical: https://hextaui.com/blocks/prompt-input Last updated: 2026-10-22 ## Overview The composer is the part of a chat people touch most, so every keystroke has to feel right. Prompt Input starts as one calm line with the + on the left and send on the right, grows into a card once the text wraps or files are added, and settles back when cleared. Enter sends and Shift+Enter adds a line, and input methods for Japanese, Chinese and Korean are never interrupted. On touch screens Enter adds a line, since the keyboard has no Shift. Inserts go through the browser’s own undo stack, so ⌘Z always works, and long pastes become an attachment you can preview or put back inline. Everything is composed from parts that share one context. Use just the field and send button, or add file uploads with progress and retry, @ and / menus at the caret, a model picker, an effort slider, a context ring with a token and cost breakdown, dictation, tool chips, a queue for messages sent while a reply streams, and drafts that survive a reload. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/prompt-input.md ---  # Refund > A refund sheet for issuing full or partial refunds on an order. Handles prorated discounts, restocking, shipping, split payments and failed or pending refunds. Canonical: https://hextaui.com/blocks/refund Last updated: 2026-10-22 ## Overview Refund is the screen a merchant opens from an order to send money back. RefundSheet wraps it in a wide sheet on desktop and a full-height sheet on phones, and RefundForm is the same form for embedding in your own page. Each line has a quantity stepper from 0 to what’s still refundable, already refunded lines are listed as Refunded, and a summary on the right recalculates as you go. The math lives in calculateRefund(order, selection), a pure function with tests. Order-level discounts are split across lines in proportion to each line’s price, and tax in proportion to each line’s price after discount, with the largest-remainder method so the parts add up to the cent. Each unit then takes a cumulative slice of its line’s share, so refunding units one at a time adds up to exactly what refunding them together would. When the selection takes everything that’s left, the total is set to the amount still available, so earlier rounding never strands a cent. Shipping can be refunded up to what was paid minus what was already refunded. The total can be edited by hand, showing how far it is from the calculated amount, and is checked against what’s available. Money goes back to the payment methods in the order you pass them, so a gift card split shows both parts. Currencies without decimals, like yen, are handled in minor units throughout. onRefund receives a RefundRequest and can return a Refund. A succeeded refund closes the sheet, a pending one shows “Refund pending with the bank”, and a failed one or a thrown error shows its message next to the button with everything still filled in. The button guards against double submits, and refunds over half the order or the whole order ask for confirmation first. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/refund.md ---  # Reviews > Product ratings, customer photos and reviews for a product page. Handles rating filters, helpful votes, review photos and products with no reviews yet. Canonical: https://hextaui.com/blocks/reviews Last updated: 2026-10-22 ## Overview Reviews is the reviews section of a product page: an average with stars, a rating histogram, feature ratings, a size scale, a strip of customer photos and the review list. It takes an array of reviews and works out the stats itself, or takes stats from your API when you only load a page at a time. Every histogram bar is a button. Click 4 stars and the list shows only 4-star reviews, the bar stays highlighted, a removable 4 stars chip appears above the list and screen readers hear how many reviews match. Filters are single-choice, combine with With photos, search within reviews and four sort orders, and an empty result offers to clear them. With five reviews or fewer the histogram is hidden, since a distribution of three reviews says nothing. Each review shows its stars, title, body clamped at six lines with Read more, the buyer’s name with a Verified buyer badge, the variant they bought and their size feedback. Photos open a lightbox. A merchant reply sits indented under the review. Helpful votes count up straight away, one vote per review, and roll back with a message if your API fails. Rating-only and photo-only reviews lay out without empty gaps. WriteReview is a dialog, a bottom sheet on phones, with a star rating input, title, body with a minimum length, a Runs small · True to size · Runs large scale, photo uploads with previews, name and email. It validates in place, keeps the draft if the shopper closes it, and ends on “Thanks, your review will appear after a quick check.” RatingStars, RatingInput, ReviewsSummary, ReviewPhotos and ReviewList also work on their own. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/reviews.md ---  # Sales Overview > The home analytics page of a store admin. Handles stores with no sales yet, today’s unfinished numbers and reports that fail or come back incomplete. Canonical: https://hextaui.com/blocks/sales-overview Last updated: 2026-10-22 ## Overview Sales Overview is the page a merchant opens first: six KPI cards, a sales chart, a live view and three breakdowns, under a date range picker with a compare-to control. You pass loaders that take a query and return data, and the block owns loading, refreshing, errors and retries for each card on its own. Every KPI card shows its value, a change chip and the period it’s compared with, like “vs Aug 23–Sep 21”. The chip colors by whether up is good for that metric, reads New when the previous period was zero instead of a meaningless ∞%, and shows a dash when there is nothing to compare. When the range changes, only the digits that changed roll; nothing counts up on first load. Today is never a finished number. Its point on the chart and every sparkline is drawn dotted, the tooltip says “so far”, and the Today preset compares with yesterday at the same time instead of the whole day. Hovering any chart moves one crosshair across all six sparklines and the main chart at once, and the card captions show the hovered day’s values. The chart picks hours for a single day, days up to two months and weeks beyond that. It can switch between sales, orders and average order value, and View as table shows the same numbers as an accessible table. An empty store shows zeros with a Share your store button, a failed report shows its error with Try again in its own card, and a metric your source can’t provide says so rather than showing a zero. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/sales-overview.md ---  # Save Bar > A floating save bar that morphs like the Dynamic Island. Handles saving, a Saved check, errors with Try again and a nudge when someone tries to leave. Canonical: https://hextaui.com/blocks/save-bar Last updated: 2026-10-22 ## Overview IslandBar is the save bar that floats at the bottom of a page while there's something to save. It's a dark pill that reads “Unsaved changes · Discard · Save ⌘S”. It rises from a small dot below the page and stretches sideways to fit its content, then shrinks back into the dot when there's nothing left to save. Every state change is one shape changing size, the way the Dynamic Island does it. The bar animates its real width and height with springs generated from Apple's own spring equations, so the corners stay round at every frame and the text never stretches. It overshoots slightly as it grows and settles without a bounce as it shrinks. The old content blurs out while the new content sharpens in, a beat after the shape starts moving. Saving shrinks the pill to a spinner. It stays there for at least 400ms so a fast save never flickers, then a check draws itself next to Saved and the bar leaves after 1.4 seconds. If the save fails, the pill widens into the error with Try again and Discard, and the draft is untouched. Edit during the Saved moment and it goes straight back to Unsaved changes. When someone tries to leave with unsaved changes, call nudge(). The bar swells for a moment, the Save button rings, and screen readers hear why. useIslandBar wires most of this for you: it tracks the async save, binds ⌘S or Ctrl+S, asks the browser before the tab closes, and gives you guard() for links. With reduced motion turned on, the bar only fades: sizes snap and nothing bounces. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/save-bar.md ---  # Security > The Security section of an AI product’s settings. Handles sessions, two-factor with recovery codes and deletion behind a typed confirmation. Canonical: https://hextaui.com/blocks/security Last updated: 2026-10-22 ## Overview Every AI product ends up with the same security page: where you’re signed in, how you sign in, and how to leave. Security is that page, built on the Settings block’s groups and rows, with every flow wired to async callbacks you own. Active sessions lists each device with its browser, system, location and when it was last active, in plain relative time. This device is marked and can’t be signed out from here. Signing out of one device shows progress in its button, then the row folds away and focus moves to the next row. Signing out everywhere else asks first and names the devices it will sign out. Change password checks as you type: a four-step strength meter and a checklist of what’s still missing, without blocking anything you type. If your server says the current password is wrong, the message shows under that field and focus goes back to it, with everything you typed kept. You can sign out other sessions in the same step. Two-factor setup draws a real, scannable QR code for the otpauth link your server returns, shows the setup key with a copy button for when scanning isn’t possible, and on a phone offers to open the link in an authenticator app. The 6-digit code checks itself as soon as it’s complete, shakes and clears on a wrong code, then shows recovery codes to copy or download as a text file. Turning it off asks first. Passkeys calls your WebAuthn flow and handles the browser’s answers: closing the prompt adds nothing and shows no error, and a device that already has a passkey says so. Deleting the account needs the exact phrase, lists what goes with it, and keeps the dialog open with your message if the server says no. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/security.md ---  # Settings > The settings page of an AI product. Handles a save bar that appears only when something changed, field errors and loading states. Canonical: https://hextaui.com/blocks/settings Last updated: 2026-10-22 ## Overview Cursor, Claude and Codex all settled on the same settings page: a filled sidebar with search and a handful of grouped sections, and on the right, cards of rows with a label and description on the left and a quiet control on the right. Settings is that page. It holds your sections and handles the parts every settings page gets wrong: losing edits, saving twice, and the jump from a sidebar on desktop to a list on a phone. Rows take any control. SettingsSelect is the compact value picker those apps use, a small outlined button that opens a menu of choices, and SettingsNumber is a stepper you can hold to repeat. Both are named by its row so screen readers hear "Chat font, Serif". SettingsLink is a row that opens something else, with a chevron or an arrow for links that leave the app. SettingsNested slides open dependent options under a switch, like network access under Run code. Search filters the sidebar by label, description and keywords, and Enter opens the first match. SettingsChoice turns a choice into picture cards, so people pick a theme or a density by what it looks like. Nothing saves until you say so. As soon as a value differs from what's saved, a dark island rises from the bottom with Discard and Save, and the section's entry in the sidebar gets a dot. Change it back and the bar goes away. Try to open another section, go back on a phone or close the tab, and the switch is blocked: the bar shakes and says to save or discard first, and the browser asks before the tab closes. ⌘S or Ctrl+S saves from anywhere. Saving shows its progress in the button, then the island shrinks to a Saved check and slides away. If your checks fail, the fields show their errors, focus moves to the first one, and the bar says how many to fix. If the server says no, return errors for the fields or throw, and the draft stays exactly as typed. Keep typing while it saves and the bar stays up for the newer edits. On a phone the sidebar becomes a grouped list with descriptions and chevrons. Tapping a section slides it in over the list with a back button, and focus moves to its heading. While a section's data loads it shows a skeleton shaped like rows of switches, or your own through the skeleton prop, and an error with Try again if loading fails. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/settings.md ---  # Shipping Methods > Delivery options for checkout and delivery dates for product pages. Handles order cutoffs, store pickup and rates that change with the address. Canonical: https://hextaui.com/blocks/shipping-methods Last updated: 2026-10-22 ## Overview ShippingMethods is the delivery step of a checkout. Each option is a radio card that leads with the date it arrives, “Mon, Oct 26 – Wed, Oct 28” or “Tomorrow”, then the method and carrier, with the price on the right. Shoppers compare dates more easily than “3–5 business days”, so the block works out real dates from business days, skipping weekends and any holidays you pass. A rate can have an order cutoff. Before it, the card says “Order within 3 h 12 min for delivery tomorrow”, updated once a minute and never ticking seconds. When the cutoff passes, the estimate moves to the next business day on its own. The fastest paid option gets a small badge, and the cheapest one does too when it isn’t already free. Pickup options sit behind a Ship / Pick up switch that only appears when both exist. A pickup card shows when the order is ready, “Ready today after 2 PM”, with the store name, distance and address. Switching back remembers the shipping option you had. The block owns the hard states: skeleton cards the same shape as the real ones while rates load, an empty state with Change address when nothing ships there, an inline error with Retry, and rates that change after an address change. If the chosen option is still offered it stays selected; if not, the cheapest one is picked and the block says “Express isn’t available for this address”. DeliveryEstimate brings the same dates to a product page, with a ZIP code popover and a returns line. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/shipping-methods.md ---  # Stack Trace > A crash shown the way a developer reads it. Your code comes first, framework frames fold away and every cause is listed in order. Canonical: https://hextaui.com/blocks/stack-trace Last updated: 2026-10-22 ## Overview When an agent’s command, tool call or test fails, the useful part of the error is buried in fifty lines of framework internals. Stack Trace puts the error type and message first, shows your own frames in full contrast with file, line and column, and folds every run of framework frames into one quiet row like “8 framework frames · next”. parseStackTrace reads V8 stacks from Node, Chrome, Bun and Deno, Firefox and Safari stacks, Vitest frames with the code under them and Python tracebacks, including chained causes from [cause], Caused by: and Python’s “direct cause” and “during handling” sections. It classifies node_modules, node:internal, Next.js internals, site-packages and the standard library as non-app code, and turns file:// and webpack-internal paths into readable project paths. Lines it doesn’t recognise are kept, never dropped. The frame where your code failed can show its source with the failing line highlighted, using Code Block. Long messages clamp with Show more, Copy gives back the original text, and frames open in your editor through getFrameHref or onFrameClick. The compact variant is a single “Failed: TypeError: …” line for a failed tool call that opens into the same frames. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/stack-trace.md ---  # Storefront > A complete store built from the HextaUI commerce blocks. Handles browsing, filters, the bag, checkout and order tracking on one shared store. Canonical: https://hextaui.com/blocks/storefront Last updated: 2026-10-22 ## Overview Storefront is a whole online shop for Halden, the home goods brand every commerce block uses, put together from the other blocks. The header search is Product Search, the bag is Cart, every grid and rail is Product Card, the collection page is Product Filters, the product page is Product Gallery, Variant Picker, Price, Reviews and the Delivery Estimate from Shipping Methods, checkout is Checkout, and the last two pages are Order Confirmation and Order Tracking. Storefront adds only the glue: a header and footer, routing, one shared store and small page layouts. There are nine pages: Home with a hero, shop-by-room tiles, a New arrivals rail and an editorial band; a collection page with filters in a sidebar on wide screens and a sheet on phones, a sort and density toolbar, removable chips and Load more; a product page; search results; a wishlist; your orders; a full-page checkout with its own minimal header; the order confirmation; and order tracking. The demo catalog has 37 pieces across Living, Bedding, Kitchen and Lighting, with sales, low stock, a pre-order and sold-out items. Everything reads from one store, so state follows the shopper. Quick add on a card, Add to bag on a product page and the bag drawer all change the same cart, and the bag count in the header rolls on every page. Hearts on cards and the product page fill the same wishlist, products you open join Recently viewed, and a placed order shows up under Your orders with its tracking. The bag shows how far you are from free shipping over $150. Routing lives in the block. Pages are hash URLs like #/collections/living?color=Oat&sort=newest, so Back and Forward work, links open in a new tab, and the filters, sort, Load more page and chosen variant survive a reload. Going back puts you where you were scrolled. Only the page scrolls: the header stays pinned, the frame fills its container, and pages cross-fade in 150 ms, or not at all with reduced motion. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/storefront.md ---  # Streaming > Text that streams from a model at a steady pace. Bursty chunks are smoothed out, with a fade on new words and a caret while it writes. Canonical: https://hextaui.com/blocks/streaming Last updated: 2026-10-22 ## Overview Models send text in bursts: a few words, a pause, then a whole sentence at once. Printing each chunk as it lands makes a reply stutter. Streaming keeps what you have received separate from what you show, and reveals it at a steady 90 characters a second. When chunks pile up, the pace rises to close the gap in about 0.3 seconds, and once the stream ends the rest is flushed in about 0.12 seconds, so the text never trails far behind the model. Emoji and other multi-part characters are never split mid-reveal, and if the text is replaced rather than appended, as after a regenerate, the reveal restarts from what the two versions share. Text that isn’t streaming renders in full on the first frame, so history and server renders never animate. StreamingText adds a soft fade on the newest words and a caret while it writes. useSmoothText gives you the pacing alone, to put in front of any renderer, including Markdown. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/streaming.md ---  # Subagents > The runs an agent hands to other agents, one line per run. Handles parallel runs, stop and retry, and a summary once each run is done. Canonical: https://hextaui.com/blocks/subagents Last updated: 2026-10-22 ## Overview Coding agents like Claude Code, Codex and Cursor hand parts of a job to other agents, often several at once. Subagents gives each of those runs one line that reads like a person delegating: the agent, its task in plain words, a live label of what it’s doing (“Reading auth/session.ts”), a timer and how many tools it has used. Runs start folded, so a busy reply stays short. Each line keeps saying what its run is doing, and opening it shows the tool calls streaming into a short window that follows the newest step. When a run finishes, its line turns into a past-tense summary such as “Mapped the token refresh flow · 14 tool uses · 32s”, with the first sentence of its report underneath and the full report inside. Parallel runs share a header that reads “Running 3 agents” with a progress bar, then “3 agents finished in 48s”. Runs can be queued, running, done, failed with a reason and Retry, stopped, or left running in the background. getSubagentFromPart reads an AI SDK tool whose output streams the subagent’s own messages, and the nested steps render with Tool Calls and the report with Markdown. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/subagents.md ---  # Team > The team page of an AI product’s workspace settings. Handles seats running out, pending invites and ownership transfer with a typed confirmation. Canonical: https://hextaui.com/blocks/team Last updated: 2026-10-22 ## Overview Every AI product with workspaces ends up with the same page: who's on the team, what each person can do, who's been invited and how many seats are left. Team is that page as one component you drop into a settings section. It reads your members, invites and seat count, and calls your handlers when someone acts. It never changes the data on its own, so what it shows is always what your server says. The invite box takes addresses the way people actually have them. Type and press comma, space or Enter, or paste a column from a spreadsheet, a To: line from an email or a list with names like Ana Lima <ana@acme.com>. Each address becomes a chip. Duplicates are dropped, words that aren't addresses are skipped when you paste, and chips for invalid addresses, existing members and people who already have an invite are flagged with the reason, plus a button to remove them all at once. Pick the role, add an optional note, and send. The seat meter shows members, pending invites and the chips you're typing as three layers, so you see the cost of an invite before you send it. Expired invites don't hold a seat. When the invites would go past the limit, sending is blocked with how many to remove, and at the limit the meter turns into an Add seats call to action. Each member row has the person's role as a menu with what each role can do. The guard rails are built in: the only owner can't demote themselves or leave until they transfer ownership, and the menus say so instead of quietly hiding the option. Admins can't touch owners. Making someone an owner or lowering your own role asks first. Transferring ownership asks you to type the new owner's email, so the wrong Ana never gets the keys. Pending invites show when they were sent, when they're about to expire and when they did. Resend renews the link and starts a cooldown counted from the last send, so the countdown survives a reload. Copy invite link puts the real link on the clipboard. Removing a member asks once, then offers Undo, and focus moves to the next person instead of falling back to the top of the page. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/team.md ---  # Test Results > An agent’s test run, shown as it happens. Tests stream in and fold into a summary, with every failure left open and its diff in view. Canonical: https://hextaui.com/blocks/test-results Last updated: 2026-10-22 ## Overview When an agent runs your tests, the chat should show what a developer looks for: how far along it is, what failed and why. While tests run, Test Results shows a live “Running tests · 42 of 120” line with counts that tick digit by digit and a bar split into passed, failed and skipped. Tests stream into their files as they finish, and the file that’s running stays open. When the run ends, the line turns into a past-tense summary such as “118 passed, 2 failed in 4.2s”. A clean run folds away. A failing one stays open with passing files folded and failing files open, unless you opened or closed them yourself. Each failure shows its message, a word-level Expected and Received diff and its stack through Stack Trace, with your frames first and framework frames folded. Timeouts and snapshot mismatches get their own wording. Filter by All, Failed, Skipped or Slow, copy a failure as text, open frames in your editor, and send Ask to fix, Rerun failed, Rerun and Update snapshot back to the agent. fromVitestJson, fromJestJson, fromPlaywrightJson and fromJUnitXml turn reports into a run, and applyTestEvent folds live events into one. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/test-results.md ---  # Thinking > The thinking view of an AI chat. A live label follows each step, searches and sources fold into a trail, and citations sit beside the answer. Canonical: https://hextaui.com/blocks/thinking Last updated: 2026-10-22 ## Overview Long waits feel shorter when you can see the work happening. Thinking puts a live status line at the top of an answer: a small shader orb, the current step in plain words such as “Searching the web”, and a running timer. Open it to read the full trail of searches, sources and reasoning. Reasoning written as a bold heading followed by a paragraph splits into sections, and half-typed headings are held back until they close. Tool steps show a spinner and a present-tense label while they run, then switch to what they did, with source chips underneath. The trail opens while the model works and collapses to “Thought for 12s” when it finishes, unless someone has opened or closed it themselves. The answer then cites its sources inline: CitedText turns [1] and [2][3] into compact chips with the title, domain and snippet on hover. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/thinking.md ---  # Tool Calls > The list of what an agent does, one line per step. Reads fold into a summary, edits and errors stay in view, and approvals ask before a tool runs. Canonical: https://hextaui.com/blocks/tool-calls Last updated: 2026-10-22 ## Overview Agents can take dozens of small steps before they answer. Showing every one buries the answer, and hiding them makes the agent feel like a black box. Tool Calls gives each step one quiet line that reads like a sentence, such as “Read components/search.tsx” or “Searched for useResults, 3 results”. Reads, searches and lookups that run back to back fold into a single summary like “Explored 6 files”. Anything that changes something, needs a decision or fails stays on its own line, with a live timer while it runs. Open any step to see the real work: the file, the diff, the terminal or the results. Every AI SDK tool state has its own look and wording, including approvals. Approving offers Allow, Deny, Always allow and “Tell it what to do instead”, which sends your words back as the reason, with ⌘↵ and ⌘⌫ from the keyboard. getToolPartStatus maps tool parts for you, and ready-made views cover search results, file lists, multiple-choice questions and raw JSON. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/tool-calls.md ---  # Variant Picker > Color swatches and size buttons for a product page. Handles sold-out sizes, combinations that don’t exist, a missing size on add to bag and back-in-stock emails. Canonical: https://hextaui.com/blocks/variant-picker Last updated: 2026-10-22 ## Overview Variant Picker shows a product’s options the way shoppers expect: colors as swatches, sizes as buttons, never a dropdown that hides what’s in stock. It works out every option from the variants you pass, so each value knows whether it’s available, sold out or not made in the current combination. Availability follows the other choices. A color stays available while any of its sizes is in stock, and a size is crossed out only for the colors it’s sold out in. Sold-out values stay selectable, so a shopper can pick one and ask to be emailed when it’s back. Sizes a color isn’t made in are disabled and say so. Picking a color that doesn’t come in the chosen size clears the size and tells screen readers why. One ring slides between the chosen swatch or size. Hover a swatch and the label previews its name while onPreviewChange lets the product image follow. Sizes are never preselected: validate() flags a missing option with “Select a size”, focuses it and gives it a small shake, which reduced motion turns off. VariantAvailability reads the chosen variant as In stock, Only 3 left, Pre-order with the ship date, or Backordered. NotifyMe collects an email for a sold-out variant. The helpers, findVariant, getOptionStates, getInitialSelection, getPriceRange and the search param pair, work on their own, on the server too. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/variant-picker.md ---  # Voice Mode > Voice conversations with an AI assistant. Handles listening, interruptions and captions, in a full-screen session or an in-chat voice pill. Canonical: https://hextaui.com/blocks/voice-mode Last updated: 2026-10-22 ## Overview Voice Mode is the visual and the controls for talking to an assistant. Pick one of eight shader styles (Sky, Dither, ASCII, CRT, Ferrofluid, Halftone, Ring or Aura) or four plain dots. Each listens, thinks and answers while moving with the sound, and monochrome styles follow your light or dark theme. Audio levels are smoothed and measured against a learned noise floor, so a quiet room reads as quiet and the motion stays soft. Rendering pauses when the visual is off screen or the tab is hidden, and reduced motion holds every style still. VoiceSession lays it out full screen at phone width, with captions, a status line, and mute and end within reach of a thumb. Tap the visual, press Space or just start talking to interrupt. VoiceComposer is a compact version that replaces the composer inside a chat. useBrowserVoice runs a complete loop on the browser’s own speech recognition and speech: it waits for a pause before answering, can stay silent and show replies as captions, and ignores its own words when they come back through the speakers. For realtime voice APIs, pass the microphone and reply streams to useAudioLevels and set the state from the session’s events. Installation, examples, theming, keyboard support, API reference and source: https://hextaui.com/blocks/voice-mode.md ---  # How to build a one-page checkout in React and Next.js that survives declines and changed prices > A checkout form is easy. Declines, 3-D Secure, prices that change before Pay and payments that never answer are not. A one-page checkout in React and Next.js. Canonical: https://hextaui.com/blog/one-page-checkout-react-nextjs Last updated: 2026-10-22 By Preet Suthar · 2026-10-22 · 6 min read Most checkout tutorials end at a form and a Pay button that calls Stripe. That part works on the first try. What loses orders is everything around it: the card that gets declined, the bank that wants a 3-D Secure check, the shipping rate that changes with the ZIP code, the request that never comes back and the shopper who presses Pay a second time. This is how I structure a one-page checkout in React and Next.js, with the states that matter and a small piece of code for each. It works with shadcn/ui or any other component set. The hard part is the flow, not the styling. ## One page, three steps that fold up A one-page checkout keeps everything in view: no page loads between steps, and the browser's Back button can't throw away half a form. But one long form is a wall. The fix is three steps on the same page, contact, delivery and payment, where only one is open at a time. When a step is done it folds into a summary row, so a finished checkout reads like a receipt: ```text Contact maya@example.com Change Ship to 12 Mission St, San Francisco, CA 94110 Change Method Standard · Arrives Oct 26 – 28 · Free Change ``` The state behind it is small. Keep the list of finished steps and derive the open one: ```ts const steps = ["contact", "delivery", "payment"] as const type Step = (typeof steps)[number] function openStep(done: Step[], editing: Step | null): Step { return editing ?? steps.find((step) => !done.includes(step)) ?? "payment" } ``` Two details make it feel right. When someone presses Change, move focus to the heading of the step that opened, or keyboard and screen reader users are left on a button that no longer exists. And when the shopper is signed in, skip contact and start at delivery with their default address. On wide screens the order summary sits beside the form. On phones it folds into a "Show order summary" bar above the form that still shows the total, because the total is the one number people keep checking. ## Validate on blur, summarize on Pay Show a field's error when the shopper leaves it, then update it live as they type so it clears the moment it is fixed. Never while they are still typing the first time. Don't disable Pay until the form is valid. A disabled button can't tell anyone what is missing. Let them press it, then put one summary at the top that lists every problem, link each item to its field and move focus to the summary. The GOV.UK Design System's error summary is a good reference for the pattern. ## Rates and taxes follow the address Shipping rates and tax depend on the address, so they can only load once the address is complete. Wait for a short pause in typing, cancel the previous request when the address changes again, and show "Calculating…" in the summary instead of a stale number. ```ts useEffect(() => { if (!isComplete(address)) return const controller = new AbortController() const pause = setTimeout(async () => { setQuote({ status: "loading" }) try { const [rates, tax] = await Promise.all([ getRates(address, controller.signal), estimateTax(address, controller.signal), ]) setQuote({ status: "ready", rates, tax }) } catch { if (!controller.signal.aborted) setQuote({ status: "error" }) } }, 300) return () => { clearTimeout(pause) controller.abort() } }, [address]) ``` When new rates arrive, keep the chosen rate if it is still offered. If it isn't, pick the cheapest one and say so: "Express isn't available for this address." Silently switching the method is how people end up paying for shipping they didn't choose. ## Express pay goes first Apple Pay, Google Pay, Shop Pay and PayPal replace the whole form, so they belong at the top, above contact, with an "Or pay with card" divider under them. Putting them next to the Pay button means the shopper has already typed their address by the time they see the faster way. Only render wallets the browser can actually use. Stripe's Express Checkout Element and similar SDKs work that out for you. ## Pay is a state machine, not a boolean `isSubmitting` can't describe what happens after Pay. Give the server's answer a type instead: ```ts type PlaceOrderResult = | { status: "succeeded"; orderId: string } | { status: "declined"; code: string } | { status: "requires_action"; clientSecret: string } | { status: "changed"; changes: PriceChange[] } ``` Then handle every case on purpose. Pay can't run twice. A double click fires two handlers before React re-renders, so a `disabled={pending}` check is not enough. Guard with a ref, and lock the Change buttons while an order is placing so the cart can't move under the payment. ```ts const placing = useRef(false) async function pay() { if (placing.current) return placing.current = true try { handleResult(await placeOrder(draft, attemptKey)) } finally { placing.current = false } } ``` Every attempt gets an idempotency key. Create it with `crypto.randomUUID()` when Pay is pressed and send it with the payment request. Stripe and most payment APIs accept one, and a retried request with the same key can't charge twice. Leaving mid-payment asks first. Add a `beforeunload` listener while a payment runs and remove it when it settles. ## Declines need words, not "Something went wrong" A decline is the most common failure in checkout and the one with the worst copy. Map the codes you get back to sentences that tell people what to do, move focus to the message and keep the card details filled in: ```ts const declineCopy: Record<string, string> = { insufficient_funds: "Your card has insufficient funds. Try another card.", expired_card: "This card has expired. Check the date or use another card.", incorrect_cvc: "The security code doesn't match. Check it and try again.", } const fallbackDecline = "Your bank declined this payment. Try another card or contact your bank." ``` `requires_action` is not an error. It means the bank wants 3-D Secure, which is routine in Europe under strong customer authentication. Keep the processing state, open the bank's challenge in a dialog labelled "Confirm with your bank" and continue when it resolves. ## When the price changed since the cart Prices, stock and discounts can change between the cart and Pay. Send the total the shopper saw with the order, reprice on the server and refuse to charge if they differ: ```ts "use server" export async function placeOrder(draft: Draft, key: string) { const cart = await repriceCart(draft.lines) if (cart.total !== draft.expectedTotal) { return { status: "changed", changes: diffLines(draft, cart) } as const } return chargeAndCreateOrder(cart, draft, key) } ``` On the client, update the summary, strike through the old total and list each change in plain words, such as "Ring vase is now $74, was $68." The shopper presses Pay again at the new amount. An item that sold out during checkout works the same way: take it out of the total, flag it and let them remove it or continue without it. ## When the payment never answers Sometimes the request hangs. The worst thing you can show after a timeout is "Try again", because the first charge may have gone through. After a reasonable wait, say "Checking your payment status…" and poll a status endpoint with the same idempotency key until you know whether an order exists. Only offer a new attempt when the server says the old one failed. ## A checklist - Steps fold into summary rows, and Change moves focus to the reopened step. - Errors on blur, one linked summary on Pay, no disabled Pay button. - Rates and tax wait for a full address, cancel stale requests and never show a stale total. - Express wallets at the top, only the ones the browser supports. - A ref guard, an idempotency key and a `beforeunload` prompt around Pay. - Specific copy per decline code, with the form still filled in. - 3-D Secure as a step, not an error. - Changed prices and sold-out items stop the charge and explain themselves. - A timeout checks status instead of offering to pay again. ## Building it with shadcn/ui shadcn/ui gives you the inputs, radio groups and collapsibles for all of this. The flow above is the part you write yourself, and it is most of the work. I built it once as the [Checkout](https://hextaui.com/blocks/checkout) block in HextaUI Pro, made from the free HextaUI components. It takes the cart and three callbacks, `onGetRates`, `onEstimateTax` and `onPlaceOrder`, and handles the four results above. If `onPlaceOrder` doesn't answer within 20 seconds, it polls `onCheckStatus` with the same idempotency key instead of offering to pay again. It comes with examples for Stripe PaymentIntents with server actions, a Shopify checkout handoff and Medusa. It uses the [Payment](https://hextaui.com/blocks/payment) block for wallets, cards, declines and 3-D Secure, and the [Address Form](https://hextaui.com/blocks/address-form) for delivery. Every block has a live preview you can click through before deciding anything. If your store runs on Shopify, use Shopify's hosted checkout rather than rebuilding it. A custom checkout makes sense when you take payment yourself. ## FAQ Is a one-page checkout better than a multi-step one? For most stores, a single page with steps that fold up gets the best of both: everything stays in view, and people only face one section at a time. Should I disable the Pay button until the form is valid? No. Let people press it and show a summary of what is missing, with links to each field. How do I stop double charges? Guard the handler with a ref, send an idempotency key with every attempt, and check the status of a timed-out payment instead of letting people pay again. Where should Apple Pay and Google Pay go? At the top of the checkout, before contact details, because they replace the rest of the form. ## Related - [Product variant picker UX in React: sold-out sizes, missing combinations and back-in-stock](https://hextaui.com/blog/product-variant-picker-react) - Colors and sizes look simple until stock lives on each combination. A React variant picker for sold-out sizes, missing combinations, photos, prices and the URL. - [Shopping cart UX in React: optimistic updates, undo and money in minor units](https://hextaui.com/blog/react-shopping-cart-optimistic-updates) - A React cart that feels instant and stays correct: money in minor units, optimistic quantities with rollback, merged requests, undo and free shipping progress. - [How to build an address form that works in every country, in React](https://hextaui.com/blog/international-address-form-react) - A US address form with a country dropdown is not international. Per-country fields, postal codes, autofill tokens, address search and errors in React. - [Building an e-commerce admin dashboard in Next.js: orders, refunds and inventory](https://hextaui.com/blog/ecommerce-admin-dashboard-nextjs) - The hard parts of a Next.js store admin: two order statuses, partial bulk failures, refund math that adds up to the cent, inventory adjustments and discounts. - [shadcn/ui switched to Base UI. Here is what actually changes in your code](https://hextaui.com/blog/shadcn-base-ui-vs-radix) - shadcn/ui now defaults to Base UI instead of Radix. Every API change you will hit, the -b radix escape hatch and a migration order that does not hurt. ---  # Product variant picker UX in React: sold-out sizes, missing combinations and back-in-stock > Colors and sizes look simple until stock lives on each combination. A React variant picker for sold-out sizes, missing combinations, photos, prices and the URL. Canonical: https://hextaui.com/blog/product-variant-picker-react Last updated: 2026-10-22 By Preet Suthar · 2026-10-22 · 5 min read A shirt in three colors and five sizes is fifteen products as far as your warehouse is concerned. Stock lives on each combination, not on "Oat" or "Large". Most variant pickers ignore that. They render colors and sizes as two independent lists, and the shopper finds out that Oat doesn't come in XL when Add to bag fails. This is how to build a product variant picker in React that tells the truth about stock: sold-out sizes, combinations that don't exist, back-in-stock emails, and photos and prices that follow the choice. ## Model variants, derive options Start from the variants, because that is what your commerce API returns and what an order points at: ```ts type Variant = { id: string options: Record<string, string> available: boolean quantity?: number price: Money imageId?: string } type Product = { options: { name: string; values: string[] }[] variants: Variant[] } ``` Every value on screen gets one of three states, worked out from the variants and the rest of the current selection: - Available: some variant with this value and the other chosen options has stock. - Sold out: the combination exists but has no stock right now. - Unavailable: the combination is not made at all. ```ts type ValueState = "available" | "sold-out" | "unavailable" function getValueState( product: Product, selection: Record<string, string>, name: string, value: string ): ValueState { const wanted = { ...selection, [name]: value } const matches = product.variants.filter((variant) => Object.entries(wanted).every( ([key, chosen]) => variant.options[key] === chosen ) ) if (matches.length === 0) return "unavailable" return matches.some((variant) => variant.available) ? "available" : "sold-out" } ``` This gives you the behavior shoppers expect without special cases. A color stays available while any of its sizes is in stock. A size is crossed out only for the colors it is sold out in. Pick a different color and the sizes update. It is a pure function, so it runs on the server too. Render the first paint with the right states instead of flashing every size as available and then crossing some out. ## Swatches and buttons, never a dropdown A `<select>` hides the one thing people came to check, whether their size is in stock. Show colors as swatches and sizes as buttons, so the whole picture is visible at once. Semantically each option is a radio group. Use real radio inputs, or `role="radiogroup"` with roving focus, so arrow keys move between values and the group has a name. Expose the state to assistive technology as well, because a strike-through line is invisible to a screen reader and easy to miss for everyone else: ```tsx <label className="swatch" data-state={state}> <input type="radio" name="size" value={size} checked={selection.size === size} onChange={() => select("size", size)} disabled={state === "unavailable"} aria-describedby={state === "sold-out" ? "size-sold-out" : undefined} /> {size} </label> ``` Above the swatches, show the chosen value as text ("Color: Oat"). On hover, preview the hovered value's name there, so people don't have to guess a color from a 32px circle. ## Sold out should still be selectable The common mistake is to disable sold-out sizes. That hides the most useful information, which sizes exist, and it removes the path to a back-in-stock email. Keep sold-out values selectable. When the chosen variant is sold out, swap Add to bag for a "Notify me when it's back" form that stores the variant id, not the product id, so the email is about Oat in Large rather than "this shirt". Only combinations that don't exist should be disabled, and they should say why in the accessible name: "XL, not made in Oat". ## Don't preselect the size Preselecting the first size is how stores ship a lot of size S. Preselect the color, since it is what the photo already shows, and leave size empty. When someone presses Add to bag without a size, don't silently fail and don't open an alert. Mark the size group with "Select a size", move focus to it and give it a short shake that reduced motion turns off. ```ts function addToBag() { const missing = product.options.find((option) => !selection[option.name]) if (missing) { setError(missing.name, `Select a ${missing.name.toLowerCase()}`) groupRefs.current[missing.name]?.focus() return } add(findVariant(product, selection)) } ``` ## Switching to a combination that doesn't exist The shopper has Large selected, then picks a color that only comes in Small and Medium. You have two choices: block the color, or accept it and clear the size. Clearing the size is better, because color is usually the bigger decision. But tell them. A polite live region with "Large isn't made in Rust. Select a size." keeps screen reader users from adding the wrong thing, and the visible size group shows the empty selection for everyone else. ## Photos and price follow the choice When a color changes, the gallery should go to that color's photo. Crossfade to it in place rather than sliding past every image in between, and wait for the new image to decode so the frame never flashes empty. Let the shopper keep browsing the other photos afterwards. The variant decides where the gallery starts, not where it is locked. Prices can differ per variant too. Before a full selection, show a range, "From $28". Once a variant is chosen, show its price, its compare-at price struck through if it is on sale, and its stock in words: "Only 3 left", "Pre-order, ships Nov 12" or "Backordered". Use tabular figures for the price so the line doesn't shift when the digits change. ## Put the selection in the URL `?color=Oat&size=L` makes a variant shareable, survives a reload and lets ads and emails link to the exact product a shopper saw. Read it back carefully, dropping anything the product doesn't have: ```ts function selectionFromSearchParams(product: Product, params: URLSearchParams) { const selection: Record<string, string> = {} for (const { name, values } of product.options) { const value = params.get(name.toLowerCase()) if (value && values.includes(value)) selection[name] = value } return selection } ``` In Next.js, read `searchParams` in the page so the server renders the right variant, and update the URL from the client when the selection changes. Decide whether each change should add a history entry or replace the current one, and be consistent about it. ## A checklist - Derive option states from variants: available, sold out, unavailable. - Swatches and buttons in radio groups, with the state in the accessible name. - Sold-out values stay selectable and offer a back-in-stock email per variant. - Size is never preselected, and a missing size is flagged and focused. - A color change that invalidates the size clears it and says why. - The gallery and price follow the variant without locking the gallery. - The selection lives in the URL. ## The HextaUI blocks for this I built these rules into the [Variant Picker](https://hextaui.com/blocks/variant-picker) block in HextaUI Pro. It works out every option from the variants you pass, keeps sold-out values selectable with a NotifyMe form, never preselects sizes and flags a missing one with "Select a size". Its helpers, `findVariant`, `getOptionStates`, `getInitialSelection`, `getPriceRange` and the search param pair, work on their own, on the server too, and `fromShopify` maps a Storefront API product. It pairs with [Product Gallery](https://hextaui.com/blocks/product-gallery), which crossfades to a variant's photo when you pass `activeId`, and [Price](https://hextaui.com/blocks/price), which formats any currency and rolls only the digits that changed. All three have live previews you can try before buying. If you are building the cart next, the same care applies there: [shopping cart UX in React](https://hextaui.com/blog/react-shopping-cart-optimistic-updates). ## FAQ Should sold-out sizes be disabled? No. Keep them selectable and offer a back-in-stock email. Disable only combinations that are not made at all. Should I preselect a size? No. Preselect the color if you like, and validate the size when someone adds to bag. Swatches or dropdown for variants? Swatches and buttons. A dropdown hides stock, which is the information people are looking for. How do I keep a variant in the URL? Use one search param per option, read it on the server for the first render, and ignore values the product doesn't have. ## Related - [How to build a one-page checkout in React and Next.js that survives declines and changed prices](https://hextaui.com/blog/one-page-checkout-react-nextjs) - A checkout form is easy. Declines, 3-D Secure, prices that change before Pay and payments that never answer are not. A one-page checkout in React and Next.js. - [Shopping cart UX in React: optimistic updates, undo and money in minor units](https://hextaui.com/blog/react-shopping-cart-optimistic-updates) - A React cart that feels instant and stays correct: money in minor units, optimistic quantities with rollback, merged requests, undo and free shipping progress. - [How to build an address form that works in every country, in React](https://hextaui.com/blog/international-address-form-react) - A US address form with a country dropdown is not international. Per-country fields, postal codes, autofill tokens, address search and errors in React. - [Building an e-commerce admin dashboard in Next.js: orders, refunds and inventory](https://hextaui.com/blog/ecommerce-admin-dashboard-nextjs) - The hard parts of a Next.js store admin: two order statuses, partial bulk failures, refund math that adds up to the cent, inventory adjustments and discounts. - [shadcn/ui switched to Base UI. Here is what actually changes in your code](https://hextaui.com/blog/shadcn-base-ui-vs-radix) - shadcn/ui now defaults to Base UI instead of Radix. Every API change you will hit, the -b radix escape hatch and a migration order that does not hurt. ---  # Shopping cart UX in React: optimistic updates, undo and money in minor units > A React cart that feels instant and stays correct: money in minor units, optimistic quantities with rollback, merged requests, undo and free shipping progress. Canonical: https://hextaui.com/blog/react-shopping-cart-optimistic-updates Last updated: 2026-10-22 By Preet Suthar · 2026-10-22 · 6 min read A shopping cart is the first piece of a store that has to feel instant and be correct at the same time. Press plus and the number should change now, not after a round trip. But the server owns stock, prices and discounts, and it will sometimes say no. This is how I build a cart in React and Next.js that does both: money stored as integers, optimistic updates that roll back cleanly, merged requests, undo instead of confirm dialogs, and a free shipping bar that doesn't lie. ## Start with money Before any UI, fix how you store money, or every total after this will be slightly wrong. ```ts 0.1 + 0.2 ``` That is `0.30000000000000004`, and a cart adds a lot of numbers. Store amounts as integers in the currency's smallest unit, cents for USD and yen for JPY, which has no minor unit. This is also what Stripe and most payment APIs send and expect. ```ts type Money = { amount: number; currency: string } function addMoney(a: Money, b: Money): Money { if (a.currency !== b.currency) { throw new Error(`Can't add ${a.currency} to ${b.currency}`) } return { amount: a.amount + b.amount, currency: a.currency } } function formatMoney(money: Money, locale: string) { const format = new Intl.NumberFormat(locale, { style: "currency", currency: money.currency, }) const digits = format.resolvedOptions().maximumFractionDigits ?? 2 return format.format(money.amount / 10 digits) } ``` `formatMoney({ amount: 4800, currency: "USD" }, "en-US")` gives $48.00, and the same amount in JPY gives ¥4,800. `Intl.NumberFormat` handles symbols, grouping and decimals per locale, so 48,00 € in Germany comes for free. Payment providers have a few currencies where their minor unit differs from the ISO standard, so check your provider's list once. Refusing to add two currencies is not paranoia. It catches the bug where a cart in EUR receives a shipping rate in USD. ## Optimistic updates that roll back The cart should change the moment someone presses plus: quantity, line total and subtotal. The request runs behind it. If it fails, the line goes back to the last quantity the server confirmed and says why under the line, for example "Only 2 left in Sand / Large". React 19's `useOptimistic` fits this well. The optimistic value shows while the transition runs, and React drops it when the transition ends, so a failure rolls back without extra code: ```tsx const [cart, setCart] = useState(initialCart) const [shownCart, showChange] = useOptimistic(cart, applyLineChange) function changeQuantity(lineId: string, quantity: number) { startTransition(async () => { showChange({ lineId, quantity }) const result = await updateLine(lineId, quantity) startTransition(() => { if (result.ok) setCart(result.cart) else setLineError(lineId, result.message) }) }) } ``` Two rules keep it honest. The server returns the whole cart after every change, and that cart replaces yours, so totals, discounts and shipping always come from one place. And the line's error stays until the shopper changes that line again, because a message that disappears before it is read is the same as no message. In Next.js, `updateLine` can be a server action. Next.js hides thrown error messages from server actions in production, so return `{ ok: false, message }` for errors you want to show instead of throwing. ## Merge quick presses Someone who wants five of something presses plus four times in a second. Sending four requests creates four chances to fail and four responses that can arrive out of order. Send one request with the final quantity instead. ```ts const timers = useRef(new Map<string, ReturnType<typeof setTimeout>>()) function pressQuantity(lineId: string, quantity: number) { showLocally(lineId, quantity) clearTimeout(timers.current.get(lineId)) timers.current.set( lineId, setTimeout(() => commitQuantity(lineId, quantity), 400) ) } ``` Send the absolute quantity, never "plus one". An absolute value is safe to retry and safe to receive late. If two requests for the same line do overlap, ignore any response that is older than the latest one you sent. ## Undo instead of "Are you sure?" A confirm dialog on remove adds a step to every removal to protect against the rare mistake. Undo protects against the same mistake and costs nothing when there isn't one. Collapse the removed line into a short row, "Removed Ring Vase · Undo", for about five seconds, and slide the lines below up into place. Undo puts the line back where it was, not at the bottom. You can remove it on the server right away and add it back on undo, or wait until the row expires. Removing right away keeps the server's cart correct if the tab closes, so I prefer it, with the original position kept on the client. Announce the removal through a polite live region and keep focus somewhere sensible, on the Undo button or the next line, rather than letting it fall back to the page. ## Lines that went stale A cart can sit in a tab for days. When it is loaded again, the server should mark lines whose price changed since they were added ("Price dropped to $58") and lines that sold out. A sold-out line blocks checkout until it is removed, and the reason sits on the line itself, not in a toast. ## A free shipping bar that tells the truth "Add $12.00 more for free shipping" is one of the few cart messages people actually like. Two things to get right: - Use the same subtotal as the server. If free shipping is calculated after discounts, the bar must be too, or the bar says you qualify and checkout charges shipping. - Celebrate once. Play a short moment when the threshold is crossed, then show a quiet "You get free shipping". Don't replay it on every render or every time the drawer opens. Use a real progress element with a text label, so the bar reads as "$138 of $150" rather than a colored stripe. ## The add to bag button and the badge Small things the shopper sees on every product page: - The button keeps its width while it moves from label to spinner to check, so nothing next to it jumps. - The spinner waits about 300ms before it appears. Most adds finish faster and never need it. - The bag badge changes only the digit that changed, and the drawer opens or a short confirmation shows, so people know where the item went. ## A checklist - Money as integers in minor units, formatted with `Intl.NumberFormat`. - Never add two currencies. - Optimistic quantities, rolled back to the last confirmed cart with a message on the line. - Quick presses merged into one request with the final quantity. - Undo on remove for about five seconds, restoring the line's position. - Stale prices and sold-out lines flagged on the line, blocking checkout when needed. - Free shipping progress from the same subtotal as the server. ## The HextaUI blocks for this These are the rules behind the [Cart](https://hextaui.com/blocks/cart) block in HextaUI Pro. It has an AddToCartButton, a CartTrigger with a live count, and a CartDrawer that slides in from the right on desktop and up from the bottom on phones, plus a CartPanel for a full cart page. Quick presses merge into one request, a failed callback rolls the line back and shows your message, removed lines collapse into an Undo row for five seconds, and the same logic is exported as `useOptimisticCart` for your own layouts. Its examples cover the Shopify Storefront API and Next.js server actions. [Order Summary](https://hextaui.com/blocks/order-summary) takes the same cart shape for checkout, with discount codes, estimated taxes and lines whose price changed. Both use the money helpers from [Price](https://hextaui.com/blocks/price), which work in integer minor units and refuse to add two currencies. You can try them all in the live previews. When the cart is done, the next step is checkout: [a one-page checkout in React and Next.js](https://hextaui.com/blog/one-page-checkout-react-nextjs). ## FAQ Should I store prices as floats? No. Store integers in the currency's minor unit and only divide when formatting. Should cart updates be optimistic? Yes for quantity and remove, as long as the server's cart replaces yours after every change and failures roll back with a reason. Undo or a confirmation dialog when removing an item? Undo. It is faster when people mean it and just as safe when they don't. How do I avoid a request for every plus press? Wait a few hundred milliseconds after the last press and send the final quantity. ## Related - [How to build a one-page checkout in React and Next.js that survives declines and changed prices](https://hextaui.com/blog/one-page-checkout-react-nextjs) - A checkout form is easy. Declines, 3-D Secure, prices that change before Pay and payments that never answer are not. A one-page checkout in React and Next.js. - [Product variant picker UX in React: sold-out sizes, missing combinations and back-in-stock](https://hextaui.com/blog/product-variant-picker-react) - Colors and sizes look simple until stock lives on each combination. A React variant picker for sold-out sizes, missing combinations, photos, prices and the URL. - [How to build an address form that works in every country, in React](https://hextaui.com/blog/international-address-form-react) - A US address form with a country dropdown is not international. Per-country fields, postal codes, autofill tokens, address search and errors in React. - [Building an e-commerce admin dashboard in Next.js: orders, refunds and inventory](https://hextaui.com/blog/ecommerce-admin-dashboard-nextjs) - The hard parts of a Next.js store admin: two order statuses, partial bulk failures, refund math that adds up to the cent, inventory adjustments and discounts. - [shadcn/ui switched to Base UI. Here is what actually changes in your code](https://hextaui.com/blog/shadcn-base-ui-vs-radix) - shadcn/ui now defaults to Base UI instead of Radix. Every API change you will hit, the -b radix escape hatch and a migration order that does not hurt. ---  # How to build an address form that works in every country, in React > A US address form with a country dropdown is not international. Per-country fields, postal codes, autofill tokens, address search and errors in React. Canonical: https://hextaui.com/blog/international-address-form-react Last updated: 2026-10-22 By Preet Suthar · 2026-10-22 · 6 min read Most address forms are a US address form with a country dropdown on top. City, State, ZIP code, in that order, for everyone. Then a shopper in London has no state to pick, a shopper in Berlin types the postal code before the city out of habit, and a shopper in Tokyo has to write their address backwards. An address form is the longest form most stores have, and it is where autofill, validation and international users all meet. This is how to build one in React that works in every country you ship to. ## Country first, then the layout The country decides which fields exist, what they are called, which are required and what order they go in. So ask for the country first, preselected from the shopper's locale or IP, and build the rest from data. Some examples of how much changes: | Country | Fields after the street | Region | Postal code | | --- | --- | --- | --- | | United States | City, State, ZIP code | Required | 12345 or 12345-6789 | | United Kingdom | Town or city, Postcode | None | Like SW1A 1AA | | Germany | Postal code, City | None | 5 digits | | Japan | Postal code, Prefecture, City | Required | 123-4567 | | Canada | City, Province, Postal code | Required | Like K1A 0B1 | You don't have to research every country by hand. Google publishes the address metadata behind its libaddressinput library, with field order, labels, required fields and postal code patterns for most of the world. Pick the countries you ship to most and give them an exact format, and give every other country a plain fallback: two address lines, city, region and postal code, none of them strictly validated. ```ts type Field = "address1" | "address2" | "city" | "region" | "postalCode" type CountryFormat = { rows: Field[][] labels: Partial<Record<Field, string>> required: Field[] postalCode?: { pattern: RegExp; example: string } regions?: { code: string; name: string }[] } const countryFormats: Record<string, CountryFormat> = { US: { rows: [["address1"], ["address2"], ["city", "region", "postalCode"]], labels: { region: "State", postalCode: "ZIP code" }, required: ["address1", "city", "region", "postalCode"], postalCode: { pattern: /^\d{5}(-\d{4})?$/, example: "94110" }, }, GB: { rows: [["address1"], ["address2"], ["city"], ["postalCode"]], labels: { city: "Town or city", postalCode: "Postcode" }, required: ["address1", "city", "postalCode"], postalCode: { pattern: /^[A-Z]{1,2}\d[A-Z\d]? ?\d[A-Z]{2}$/i, example: "SW1A 1AA", }, }, } ``` The form component then renders `format.rows` and never mentions a country by name. ## Fewer fields Every field you show is one more thing to fill in and one more thing to get wrong. - One name field. "Full name", not first and last. Plenty of names don't split into two parts, and the order differs between countries. - Line 2 behind a link. "Add apartment, suite, etc." opens it. Most people don't need it. If autofill or address search fills it, show it. - Company behind a link too, for the few B2B orders. - Phone optional, with the reason. "For delivery questions only" under the field gets more numbers than a required field gets real ones. ## Autofill does most of the work Browser autofill can fill the whole form in one tap, but only if every input has a `name` and the right `autocomplete` token. Prefix the tokens with `shipping` or `billing` so the browser knows which saved address goes where: ```tsx <Input name="name" autoComplete="shipping name" /> <Input name="address1" autoComplete="shipping address-line1" /> <Input name="address2" autoComplete="shipping address-line2" /> <Input name="city" autoComplete="shipping address-level2" /> <Input name="region" autoComplete="shipping address-level1" /> <Input name="postalCode" autoComplete="shipping postal-code" inputMode={country === "US" ? "numeric" : "text"} /> <Input name="phone" type="tel" autoComplete="shipping tel" /> ``` `address-level1` is the state, province or prefecture, and `address-level2` is the city. When billing is different from shipping, render a second form with `billing` tokens, so the browser doesn't fill the billing form with the shipping address. Don't use `type="number"` for postal codes. ZIP codes start with zeros, UK and Canadian codes have letters, and number inputs come with spinners and scroll-wheel changes. Use a text input with `inputMode="numeric"` only where codes are purely digits. ## Postal code lookup In some countries the postal code already tells you the city and region. Japan is the classic case: addresses start with the postal code, and the code alone identifies the prefecture and city. When the shopper finishes the postal code, look it up and fill city and region, but never overwrite something they already typed. Their input wins over your data. ## Address search Address search, typing the start of an address and picking a suggestion, is faster than any form on mobile. Google Places and Mapbox both offer it as two calls: one that suggests addresses for what was typed, and one that turns the picked suggestion into structured fields. A few rules for wiring it up: - Wait for a pause in typing and abort the previous request, the same as any search box. - Always end the list with "Enter address manually". The street may be new, or the suggestion may be wrong. - After a pick, fill the fields and show them, so the shopper can check the result and add an apartment number. - Google's Places API uses session tokens to group the suggest and details calls of one search. Use them, or the calls may be billed separately. ## Errors that say what's wrong Validate a field when the shopper leaves it, then live as they type until it is fixed. Write the error for the country: "Enter a 5-digit ZIP code" in the US, "Enter a postcode like SW1A 1AA" in the UK. "Invalid postal code" helps no one. On submit, list every problem in a summary at the top of the form, link each one to its field and move focus to the summary. Connect each error to its input with `aria-describedby` and set `aria-invalid`, so screen readers read the message with the field. Normalize before you validate: trim spaces, uppercase UK and Canadian postcodes and accept them with or without the space. Rejecting "sw1a1aa" when you could fix it is your bug, not the shopper's. ## Switching country People change the country after typing half the address more often than you would think. When they do, keep what still fits (name, street lines, phone), clear the region if the new country has a different list, and re-check only the fields they already touched. Showing fresh errors on fields they haven't reached yet feels like being scolded for something they didn't do. ## Store the structure, not the string Save the address as fields plus an ISO country code, not as formatted lines. You will need the structure for tax, shipping rates and carrier labels, and you can always format it for display. A one-line summary such as "12 Mission St, San Francisco, CA 94110" is a view of the data, not the data. ## A checklist - Country first, then fields, labels and order from a per-country format. - An exact format for your main countries and a forgiving fallback for the rest. - One name field, line 2 and company behind links, phone optional with a reason. - A `name` and a `shipping` or `billing` autocomplete token on every input. - Text inputs for postal codes, numeric keyboards only where codes are digits. - Postal code lookup that never overwrites typed values. - Address search with a manual entry option at the end. - Country-specific error copy and a linked summary on submit. ## The HextaUI block for this The [Address Form](https://hextaui.com/blocks/address-form) block in HextaUI Pro is built on these rules. Sixteen countries have their own format with labels, required fields, region lists and postal rules, and every other country gets a plain fallback. Every input has the right autocomplete token with a shipping or billing prefix. `onSearchAddress` and `onResolveAddress` connect address search, with an example for Google Places, and the same two calls map onto Mapbox. `onLookupPostalCode` fills city and region without overwriting anything typed, and `validate()` lists every problem in a linked summary. SavedAddresses and AddressSummary cover signed-in shoppers and the finished "Ship to" row. The [Checkout](https://hextaui.com/blocks/checkout) block uses it for delivery. If you are building the rest of that page, I wrote up [a one-page checkout in React and Next.js](https://hextaui.com/blog/one-page-checkout-react-nextjs) as well. ## FAQ Should the country field come first? Yes. It decides which fields exist and what order they go in, so it has to be chosen before the rest makes sense. Should I use first name and last name fields? Use one full name field unless a carrier or payment provider requires the split. What input type should a postal code use? A text input, with `inputMode="numeric"` only for countries whose codes are all digits. Do I need address validation from an API?** It helps, but don't block the order on it. Suggest a correction and let the shopper keep what they typed. ## Related - [How to build a one-page checkout in React and Next.js that survives declines and changed prices](https://hextaui.com/blog/one-page-checkout-react-nextjs) - A checkout form is easy. Declines, 3-D Secure, prices that change before Pay and payments that never answer are not. A one-page checkout in React and Next.js. - [Product variant picker UX in React: sold-out sizes, missing combinations and back-in-stock](https://hextaui.com/blog/product-variant-picker-react) - Colors and sizes look simple until stock lives on each combination. A React variant picker for sold-out sizes, missing combinations, photos, prices and the URL. - [Shopping cart UX in React: optimistic updates, undo and money in minor units](https://hextaui.com/blog/react-shopping-cart-optimistic-updates) - A React cart that feels instant and stays correct: money in minor units, optimistic quantities with rollback, merged requests, undo and free shipping progress. - [Building an e-commerce admin dashboard in Next.js: orders, refunds and inventory](https://hextaui.com/blog/ecommerce-admin-dashboard-nextjs) - The hard parts of a Next.js store admin: two order statuses, partial bulk failures, refund math that adds up to the cent, inventory adjustments and discounts. - [shadcn/ui switched to Base UI. Here is what actually changes in your code](https://hextaui.com/blog/shadcn-base-ui-vs-radix) - shadcn/ui now defaults to Base UI instead of Radix. Every API change you will hit, the -b radix escape hatch and a migration order that does not hurt. ---  # Building an e-commerce admin dashboard in Next.js: orders, refunds and inventory > The hard parts of a Next.js store admin: two order statuses, partial bulk failures, refund math that adds up to the cent, inventory adjustments and discounts. Canonical: https://hextaui.com/blog/ecommerce-admin-dashboard-nextjs Last updated: 2026-10-22 By Preet Suthar · 2026-10-22 · 6 min read An e-commerce admin looks like a CRUD app: a table of orders, a page per order, a form per product. The tables are the easy part. The hard part is that every number in a store admin is money or stock, and both have to stay right while customers keep buying in the background. This is what I learned building the admin side of a store in Next.js: orders tables with honest statuses, an order page that shows what is left to do, refunds that add up to the cent, inventory edits that survive live orders, and discounts merchants can read. ## Orders: two statuses, not one The first mistake is a single `status` column. An order has at least two independent states: payment (pending, authorized, paid, partially refunded, refunded) and fulfillment (unfulfilled, partially fulfilled, fulfilled). "Paid and unfulfilled" is the list a merchant works from every morning, and one status column can't express it. Show them as two pills. Don't let color carry the meaning. WCAG asks that color isn't the only way information is shown, and "Partially paid" in light orange next to "Paid" in green is hard to tell apart for many people. A text label plus a small glyph, an empty, half or full circle, reads at a glance. ## Saved views live in the URL Merchants don't browse orders, they work through lists: Unfulfilled, Unpaid, Open. A saved view is just filters, a sort and a search. Keep the whole query in the URL so a link opens the same list and Back works, and read it on the server in Next.js: ```tsx type SearchParams = Promise<Record<string, string | string[] | undefined>> export default async function OrdersPage({ searchParams, }: { searchParams: SearchParams }) { const query = parseOrdersQuery(await searchParams) const page = await listOrders(query) return <OrdersTable query={query} page={page} /> } ``` When the current filters differ from the saved view, mark the tab as modified and offer Reset, Update view and Save as new view, the same way a spreadsheet tells you a filter is on. ## New orders shouldn't move the row under the cursor Orders arrive while the merchant is looking at the list. If new rows push everything down, the checkbox they were about to click becomes a different order. While a row is focused or anything is selected, hold new orders back behind a "1 new order · Show" pill, and only insert them at the top when nothing is in progress. ## Bulk actions fail partially "Mark 6 orders as fulfilled" will sometimes fulfill 5. One is on hold, or was cancelled a minute ago. Design the API for it: return the ids that failed, each with a reason, and report exactly that. ```ts type BulkResult = { succeeded: string[] failed: { id: string; reason: string }[] } ``` The message then writes itself: "Fulfilled 5 orders. 1 couldn't be fulfilled: #1031 is on hold", with a link to that order. An all-or-nothing error toast would leave the merchant guessing which ones went through. ## The order page shows what's left On the order page, split the items by what happened to them, not by how they were bought. Each shipment gets its own card with the carrier and tracking. Refunded items get theirs. And the card that matters most is what's still to ship: ```ts function unfulfilledQuantity(line: OrderLine) { return line.quantity - line.fulfilledQuantity - line.refundedQuantity } ``` The timeline under it should be built from the order's events, with short titles from the data ("Payment of $564.41 captured", "Shipped with UPS" with the tracking number linked), the exact time in a tooltip and repeated events of the same kind folded into one line. Staff comments sit in the same feed and post optimistically, with a retry if they fail. ## Refund math has to add up to the cent Refunds are where admin code most often gets money wrong. A customer bought three items with a $10 order discount and tax, and returns one. How much do they get back? Spread order-level amounts across lines in proportion to each line's price. Discounts by price, tax by price after discount. Splitting in integer cents leaves remainders, and the largest remainder method hands them out so the parts always add up to the original: ```ts function allocate(total: number, weights: number[]): number[] { const sum = weights.reduce((a, b) => a + b, 0) if (sum === 0) return weights.map(() => 0) const exact = weights.map((weight) => (total * weight) / sum) const parts = exact.map(Math.floor) let left = total - parts.reduce((a, b) => a + b, 0) const byFraction = exact .map((value, index) => ({ index, fraction: value - Math.floor(value) })) .sort((a, b) => b.fraction - a.fraction) for (const { index } of byFraction) { if (left === 0) break parts[index] += 1 left -= 1 } return parts } ``` `allocate(1000, [3000, 3000, 3000])` gives `[334, 333, 333]`, which sums to exactly 1000. There is a second trap. Refund one unit of a line today and the other two next week, and the totals must match refunding all three at once. Give each unit a cumulative slice of the line's share instead of rounding each refund on its own: ```ts function unitsShare(lineShare: number, quantity: number, from: number, count: number) { const upTo = (units: number) => Math.floor((lineShare * units) / quantity) return upTo(from + count) - upTo(from) } ``` `from` is how many units were already refunded. However the refunds are split, the slices add up to `lineShare`. The rest of the refund screen is state handling. Shipping can be refunded up to what was paid minus what was already refunded. Money goes back to payment methods in a fixed order when an order was split across a gift card and a card. Send an idempotency key so a retried request never refunds twice, ask for confirmation on large refunds, and show "pending with the bank" as its own state rather than as success or failure. ## Inventory: adjust by, don't overwrite The naive inventory editor sends the new number: "Sand / Large is 47". If two orders came in while the merchant was typing, saving 47 quietly undoes them. Send changes as adjustments instead. "Received 5" is a delta, and deltas are safe to apply on top of anything that happened in between. When the merchant really means a count, "Set to 47" after a cycle count, turn it into a delta against the quantity they saw and let the server reject it if that quantity moved: ```ts type Adjustment = { variantId: string delta: number basedOn: number reason: "received" | "cycle_count" | "damaged" | "correction" } ``` A rejected row stays in the draft with a message such as "Quantity changed to 40 by another device", and Reapply sends it again on top of the new number. Shopify's `inventoryAdjustQuantities` mutation works the same way with its `changeFromQuantity` field. Also split the number. On hand is what is in the building, but committed stock is already sold and unavailable stock is damaged or on hold. Merchants need to see available separately from on hand, or they sell stock that has already been sold. ## Discounts as a sentence Discount forms are usually a long list of fields, and merchants can't tell what they built until a customer complains. Write the offer as one sentence with editable parts, "Customers get 15% off Ring Vase and Glass Carafe", put minimum purchase, customer eligibility, usage limits, combinations and schedule in collapsed rows that show their current value, and preview a sample checkout with the discount applied. Warn about risky setups, like 100% off with no usage limit, and schedule in the store's time zone, not the browser's. ## One store, every page The last piece is consistency. Refund an item and the order's payment status, its timeline, the customer's total spent and the stock you restocked should all change together. Have every mutation return the entities it changed and update or revalidate every view that shows them. And block navigation away from unsaved product, stock or discount edits, including the browser's Back button. ## The HextaUI blocks for this These are the problems the admin blocks in HextaUI Pro are built around. [Orders Table](https://hextaui.com/blocks/orders-table) has saved views kept in the URL, separate payment and fulfillment pills with progress glyphs, and bulk actions that report partial failures. [Refund](https://hextaui.com/blocks/refund) does its math in `calculateRefund(order, selection)`, a pure function with tests that uses the largest remainder method. [Inventory](https://hextaui.com/blocks/inventory) saves adjustments, not overwrites, and lets merchants reapply rejected rows. [Discount Builder](https://hextaui.com/blocks/discount-builder) edits the offer as a sentence beside a live checkout preview. [Commerce Dashboard](https://hextaui.com/blocks/commerce-dashboard) puts them together with Order Detail, Product Editor and Sales Overview into one store admin on a shared store, with hash routes by default or your Next.js routes through its router prop, and examples that map each action to the Shopify Admin API. The live preview is the full dashboard, so you can refund an order and watch every page update. ## FAQ Should an order have one status or two? At least two: payment and fulfillment are independent, and merchants filter on combinations of them. How do I split a discount across refunded items? In integer cents, in proportion to each line's price, using the largest remainder method so the parts add up exactly. Should inventory edits send the new quantity or the change? The change. Deltas survive orders placed while the merchant was editing; a "set to" count should be checked against the quantity it was based on. Where should an admin's filters live? In the URL, so views can be shared, reloaded and navigated with Back. ## Related - [How to build a one-page checkout in React and Next.js that survives declines and changed prices](https://hextaui.com/blog/one-page-checkout-react-nextjs) - A checkout form is easy. Declines, 3-D Secure, prices that change before Pay and payments that never answer are not. A one-page checkout in React and Next.js. - [Product variant picker UX in React: sold-out sizes, missing combinations and back-in-stock](https://hextaui.com/blog/product-variant-picker-react) - Colors and sizes look simple until stock lives on each combination. A React variant picker for sold-out sizes, missing combinations, photos, prices and the URL. - [Shopping cart UX in React: optimistic updates, undo and money in minor units](https://hextaui.com/blog/react-shopping-cart-optimistic-updates) - A React cart that feels instant and stays correct: money in minor units, optimistic quantities with rollback, merged requests, undo and free shipping progress. - [How to build an address form that works in every country, in React](https://hextaui.com/blog/international-address-form-react) - A US address form with a country dropdown is not international. Per-country fields, postal codes, autofill tokens, address search and errors in React. - [shadcn/ui switched to Base UI. Here is what actually changes in your code](https://hextaui.com/blog/shadcn-base-ui-vs-radix) - shadcn/ui now defaults to Base UI instead of Radix. Every API change you will hit, the -b radix escape hatch and a migration order that does not hurt. ---  # shadcn/ui switched to Base UI. Here is what actually changes in your code > shadcn/ui now defaults to Base UI instead of Radix. Every API change you will hit, the -b radix escape hatch and a migration order that does not hurt. Canonical: https://hextaui.com/blog/shadcn-base-ui-vs-radix Last updated: 2026-10-16 By Preet Suthar · 2026-10-16 · 5 min read On 3 July 2026, `npx shadcn init` started picking Base UI instead of Radix. If you have read the headlines and nothing else, you probably think one of two things: that Radix is dead, or that nothing changed. Neither is true. I maintain [HextaUI](https://hextaui.com), a shadcn/ui registry built on Base UI, so I have spent most of this year inside both primitive layers. This is the guide I wished existed in July: what changed, what did not, every API difference you will hit, and the order to migrate in if you decide to. ## What changed, in one paragraph New shadcn/ui projects get Base UI primitives. Radix is still fully supported. The shadcn team said every update and new component ships for both libraries, unless a component only exists in Base UI. Existing projects are untouched. If you want Radix on a fresh project, you pass one flag: ```bash npx shadcn@latest init -b radix ``` If you have CI or scripts that call `init` non-interactively and expect Radix, add that flag now, before a fresh checkout surprises you. ## Why the default moved Two reasons were given. Base UI had reached a stable 1.6.0 with over six million weekly downloads, and projects created through `shadcn/create` were already choosing Base UI over Radix about two to one. The default followed what people were picking. Base UI is built by the people behind Radix, Material UI and Floating UI, and the lineage shows. It covers primitives Radix never shipped, such as Combobox, Autocomplete, Number Field, Toast and Preview Card. As of September 2026 it sits at 1.8.0. ## Should you migrate an existing app? Probably not this quarter, and not all at once. Stay on Radix if the app is stable, you are not blocked on a missing primitive, and nobody on the team has a specific complaint. Nothing you depend on is going away. Migrate if you need Combobox or Number Field without reaching for a second library, if you are already rewriting the components for Tailwind v4 anyway, or if you want to be on the layer that new shadcn/ui components target first. Either way, read the next section before you decide, because the differences are not cosmetic. ## Every API difference you will actually hit I grouped these by how they fail. The first group breaks your build. The second group compiles fine and changes behavior silently, which is worse. ### Build-breaking changes `asChild` becomes `render`. This is the one everyone meets first. ```tsx // Radix <DialogTrigger asChild> <Button>Open</Button> </DialogTrigger> // Base UI <DialogTrigger render={<Button />}>Open</DialogTrigger> ``` The `render` prop takes an element or a function. The function form gives you the state, which is useful for things like a trigger that changes its icon when open. Anchored popups gain a `Positioner`. Menu, Select, Popover and Tooltip go from `Portal > Content` to `Portal > Positioner > Popup`. Dialog has no Positioner; it uses `Backdrop` and `Popup`. `Overlay` is now `Backdrop`. Rename and move on. Select values are nullable. A controlled Select holds `Value | null`, not `string`. Your `useState<string>("")` becomes `useState<string | null>(null)`, and every place that read the value as a string needs a guard. Accordion and Toggle Group values are always arrays. Even in single mode, `value="a"` becomes `value={["a"]}`. Tabs keep a single value. `onOpenChange` has a second argument. Radix lets you call `event.preventDefault()` to stop a close. Base UI passes `(open, details)` and you call `details.cancel()`. The `details.reason` field tells you whether it was the Escape key, an outside press or something else, which is handy for "unsaved changes" dialogs. Open-state selectors change. `data-[state=open]:` variants become `data-open:`. This one hides in your `className` strings and in `cva` variants, so grep for `data-[state=` before you call the migration done. ### Silent behavior changes Tabs activate manually by default. In Radix, arrow keys move focus and activate the tab. In Base UI, arrow keys move focus and you press Enter or Space to activate. If your tests or users expect the Radix behavior, set `activateOnFocus` on the list. Checkbox and radio menu items keep the menu open. `closeOnClick` defaults to `false` for `CheckboxItem` and `RadioItem`. Plain items still close. This is arguably the better default, but it is a change your users will notice. Navigation menus open faster. Base UI's hover `delay` defaults to 50ms. Radix's `delayDuration` defaulted to 200ms. Fast menus feel great until someone sweeps their mouse across the header and three panels fire in a row. Tune it. ## A migration order that does not hurt Keep both libraries installed. Move one component per commit. Run your tests between each. In this order: 1. Leaf components with no popup: Switch, Checkbox, Slider, Toggle, Progress. Mostly rename work. 2. Tabs and Accordion. Fix the array values and decide on `activateOnFocus`. 3. Dialog and Alert Dialog. Learn the `Backdrop` and `Popup` structure and the `details.cancel()` pattern here, where there is no Positioner to confuse things. 4. Popover and Tooltip. Add the `Positioner`. 5. Select, Combobox, Dropdown Menu, Context Menu. Nullable values, `closeOnClick`, and the whole popup tree. Do these last, with the most tests. Replacing a component with the Base UI version is one CLI command, and your source is in git, so review the diff rather than trusting it: ```bash npx shadcn@latest add dialog --overwrite ``` Then `git diff components/ui/dialog.tsx` and read every line before you keep it. ## What I would not do I would not run a codemod across the whole tree and hope. The build-breaking changes are easy to find. The silent ones are not, and a codemod cannot tell you that your settings page now needs two keystrokes to switch tabs. I would also not switch primitive layers and redesign the components in the same PR. The point of shadcn/ui is that you own the code. Owning it means reading the diff. ## If you want the migration done for you HextaUI is a registry you add to a shadcn/ui project. Every component is already written on Base UI, keeps the shadcn/ui names and props, and uses the same theme tokens, so `npx shadcn@latest add https://hextaui.com/r/dialog.json --overwrite` lands a Base UI Dialog in `components/ui` next to your other files. The components are MIT and free. The [HextaUI vs shadcn/ui](https://hextaui.com/compare/shadcn-ui) page lists what is different and when plain shadcn/ui is the better pick. ## FAQ Is Radix deprecated? No. shadcn/ui ships every component for both libraries, and the team still runs Radix in production. Can I mix Radix and Base UI components in one project? Yes. You carry both dependencies while you migrate. Many projects will stay mixed for a long time and that is fine. Do I need to change my theme tokens? No. `--background`, `--primary`, `--radius` and the rest are unchanged. The primitive layer is independent of the Tailwind side. Does Base UI support React Server Components? Base UI primitives are client components, the same as Radix. Keep the `"use client"` directive where shadcn/ui puts it. Where is the official change log? The July 2026 entry is at [ui.shadcn.com/docs/changelog/2026-07-base-ui-default](https://ui.shadcn.com/docs/changelog/2026-07-base-ui-default). ## Related - [How to build a one-page checkout in React and Next.js that survives declines and changed prices](https://hextaui.com/blog/one-page-checkout-react-nextjs) - A checkout form is easy. Declines, 3-D Secure, prices that change before Pay and payments that never answer are not. A one-page checkout in React and Next.js. - [Product variant picker UX in React: sold-out sizes, missing combinations and back-in-stock](https://hextaui.com/blog/product-variant-picker-react) - Colors and sizes look simple until stock lives on each combination. A React variant picker for sold-out sizes, missing combinations, photos, prices and the URL. - [Shopping cart UX in React: optimistic updates, undo and money in minor units](https://hextaui.com/blog/react-shopping-cart-optimistic-updates) - A React cart that feels instant and stays correct: money in minor units, optimistic quantities with rollback, merged requests, undo and free shipping progress. - [How to build an address form that works in every country, in React](https://hextaui.com/blog/international-address-form-react) - A US address form with a country dropdown is not international. Per-country fields, postal codes, autofill tokens, address search and errors in React. - [Building an e-commerce admin dashboard in Next.js: orders, refunds and inventory](https://hextaui.com/blog/ecommerce-admin-dashboard-nextjs) - The hard parts of a Next.js store admin: two order statuses, partial bulk failures, refund math that adds up to the cent, inventory adjustments and discounts. ---  # The states shadcn/ui leaves to you: loading, success, error, empty and reduced motion > shadcn/ui gives you a clean button, not a loading button. The hard UI states every shadcn project hand-rolls, with the timings that make them feel right. Canonical: https://hextaui.com/blog/shadcn-ui-states Last updated: 2026-10-16 By Preet Suthar · 2026-10-16 · 5 min read Search "shadcn button loading state" and you will find a hundred snippets that do the same thing: add an `isLoading` prop, swap the label for a spinner, disable the button. Ship that and your app will feel worse than before you added it. That is not a knock on shadcn/ui. It gives you a clean starting point and leaves the states to you, on purpose. But "the states" are where most of the feel of an interface lives, and almost nobody budgets time for them. This is the list of states I handle in every component I ship, and the specific timings that separate "finished" from "works". ## 1. Loading that does not flicker The naive loading button shows a spinner the instant you click. Most requests finish in under 200ms, so what the user sees is a flash of spinner and then the result. It reads as jitter. Two rules fix it: - Wait before you show the spinner. If the request finishes within about 150ms, never show it at all. - Once shown, keep it up for a minimum time. Around 400ms. A spinner that appears for 30ms is worse than no spinner. ```ts const spinnerDelay = 150 const minimumSpinnerTime = 400 ``` That is a hook, not a prop. Here is the shape: ```tsx const { buttonProps, track } = useButtonFeedback() <Button {...buttonProps} onClick={() => track(save())}> Save </Button> ``` `track` takes the promise. The hook decides whether the request was fast enough to skip the spinner, holds the spinner long enough not to flicker, and moves the button into success or error when the promise settles. The HextaUI [useButtonFeedback](https://hextaui.com/docs/use-button-feedback) hook and [useDelayedLoading](https://hextaui.com/docs/use-delayed-loading) do exactly this, and they are small enough to read in one sitting. The same delay rule applies to skeletons. A skeleton that appears for 50ms and gets replaced by the content is a flash of grey. Delay it by 150ms, and when the content arrives, fade it in without moving anything around it. ## 2. Success and error, in place After a save succeeds, the button should say so. "Saved" with a check, for about two seconds, then back to idle. After it fails, the button should say that too, and hold the error longer, about four seconds, because people need time to read an error and decide what to do. Two details that matter more than they sound: - Do not reset while the pointer is on the button. If someone is hovering, they are reading. Reset after they leave. - Ignore clicks while the request is in flight. Not with `disabled`, which removes the button from the tab order and makes screen readers skip it. Use `aria-busy` and ignore the click. A Switch has the same problem in a smaller space. Flip it, send the request, and if the request fails, flip it back. The user needs to see the rollback, so animate it, and show a brief pending state while the save is out. ## 3. Invalid, without punishing typing Shake the field when a submit attempt finds it invalid. Never shake while someone is still typing. The rule is the trigger: validation on submit or on blur gets the shake, validation on change does not. The shake itself should be short, three or four oscillations in about 300ms, and under `prefers-reduced-motion` it becomes a color change on the border and nothing else. Native `:user-invalid` helps here. It only matches after the user has interacted, so you can style the invalid state in CSS without a `touched` flag in React. ## 4. Empty is a state, not an absence An empty list is where new users land first, and the default is a blank area with a header above it. Every empty state needs three things: an icon or illustration so the space reads as intentional, one sentence that says what will appear here, and the action that makes something appear. This is cheap to build and almost always skipped because the person building the feature has test data. Clear your database once in a while. ## 5. Reduced motion is not "no motion" `prefers-reduced-motion: reduce` is on for a meaningful share of users, and the lazy implementation is a global `* { transition: none }`. That removes the information motion was carrying. A dialog that snaps open with no fade is harder to parse than one that fades. The rule I use: anything that moves across the screen becomes a fade. Anything that fades stays a fade. Anything that loops stops. Durations get shorter, not zero. Put the check in one place so every component reads it: ```ts export function prefersReducedMotion() { return window.matchMedia("(prefers-reduced-motion: reduce)").matches } ``` And share the easing curves and durations too. If every component picks its own `cubic-bezier`, the app will feel like it was built by six people, because it was. ## 6. Motion you can interrupt Open an accordion, then close it halfway through the opening animation. In a lot of implementations, it finishes opening and then closes, or it jumps. The right behavior is to reverse from wherever it is. The Web Animations API makes this easy: keep a reference to the running animation, and on the next toggle, read its current time and animate from the current computed height. CSS transitions on `height: auto` cannot do this, and `grid-template-rows: 0fr` to `1fr` can but is harder to reverse mid-way. Pick the approach that lets you interrupt. ## 7. Touch targets and the iOS zoom Two things break on phones that you will never see on a laptop: - Inputs under 16px zoom the page on iOS Safari. Keep input text at 16px on coarse pointers even if your theme is 15px elsewhere. A single `@media (pointer: coarse)` rule covers it. - Tap targets under 44px miss. Buttons can be 32px tall on desktop and grow on touch screens through the same media query. ## 8. Right-to-left If you ever ship to Arabic or Hebrew users, every `ml-` and `pl-` and `left-` in your components is a bug. Use logical properties: `ms-`, `ps-`, `start-`. shadcn/ui added RTL support in January 2026, so new components you pull are fine, but the ones you copied in 2024 are not. ## Where this leaves you None of these is hard. All of them together is a few weeks of work on a component set the size of shadcn/ui, and the work is invisible when it is done, which is why it gets cut. I built [HextaUI](https://hextaui.com) because I kept doing this work on every project. It is a free, MIT-licensed registry you add to a shadcn/ui project. Same CLI, same component names, same theme tokens, and every one of the states above already handled, down to the 150ms spinner delay. If you would rather own the code and write the states yourself, the hooks are standalone and you can install just those. ```bash npx shadcn@latest add https://hextaui.com/r/use-button-feedback.json ``` ## FAQ Should I disable a button while loading? Set `aria-busy="true"` and ignore clicks. `disabled` removes it from the tab order and hides it from screen readers mid-action. How long should a success state show? About two seconds, longer if the pointer is still on the control. Errors about four seconds. Is a skeleton always better than a spinner? A skeleton is better when you know the shape of what is coming. A spinner is better for actions. Both need the 150ms delay. Does reduced motion mean I should remove all animation? No. Replace movement with fades, stop loops and shorten durations. Keep the information. ## Related - [How to build a one-page checkout in React and Next.js that survives declines and changed prices](https://hextaui.com/blog/one-page-checkout-react-nextjs) - A checkout form is easy. Declines, 3-D Secure, prices that change before Pay and payments that never answer are not. A one-page checkout in React and Next.js. - [Product variant picker UX in React: sold-out sizes, missing combinations and back-in-stock](https://hextaui.com/blog/product-variant-picker-react) - Colors and sizes look simple until stock lives on each combination. A React variant picker for sold-out sizes, missing combinations, photos, prices and the URL. - [Shopping cart UX in React: optimistic updates, undo and money in minor units](https://hextaui.com/blog/react-shopping-cart-optimistic-updates) - A React cart that feels instant and stays correct: money in minor units, optimistic quantities with rollback, merged requests, undo and free shipping progress. - [How to build an address form that works in every country, in React](https://hextaui.com/blog/international-address-form-react) - A US address form with a country dropdown is not international. Per-country fields, postal codes, autofill tokens, address search and errors in React. - [Building an e-commerce admin dashboard in Next.js: orders, refunds and inventory](https://hextaui.com/blog/ecommerce-admin-dashboard-nextjs) - The hard parts of a Next.js store admin: two order statuses, partial bulk failures, refund math that adds up to the cent, inventory adjustments and discounts. ---  # How to build an AI chat UI with shadcn/ui and the Vercel AI SDK that survives real users > A streaming AI chat is easy to demo and hard to ship. The states a shadcn/ui and AI SDK chat has to handle, from stop and retry to tool approvals and CJK input. Canonical: https://hextaui.com/blog/ai-chat-ui-shadcn-ai-sdk Last updated: 2026-10-16 By Preet Suthar · 2026-10-16 · 6 min read The demo takes an afternoon. `useChat` from the AI SDK, a list of messages, a textarea, and tokens stream onto the screen. Everyone on the team is impressed. Then a real person uses it. They hit Enter while composing Japanese and send half a word. They stop a reply and the UI shows nothing. A tool call wants approval mid-stream and there is no UI for that. They scroll up to re-read something and the view yanks them back to the bottom with every token. I have built this screen more times than I would like, most recently as the blocks behind [HextaUI](https://hextaui.com). This is the checklist of what a chat UI has to handle before it is done, with the shadcn/ui and AI SDK specifics for each. ## Start from message parts, not strings The AI SDK's `useChat` returns messages made of parts: text, reasoning, tool calls with their state, sources, files. Render the parts, not a concatenated string. Every feature below depends on it. ```tsx import { isToolUIPart } from "ai" {message.parts.map((part, i) => { if (isToolUIPart(part)) return <ToolCall key={i} part={part} /> switch (part.type) { case "text": return <Markdown key={i} text={part.text} /> case "reasoning": return <Thinking key={i} text={part.text} /> case "source-url": return <Source key={i} url={part.url} /> default: return null } })} ``` Tool parts are typed `tool-<name>`, so `isToolUIPart` is the reliable check. Keep your blocks free of the SDK import. Take parts as props. Then the same components work with a LangGraph backend or your own server once you map its output to the same shape. ## The composer The textarea is where most of the bugs live. Enter sends, Shift+Enter breaks a line. Everyone does this. Almost nobody handles composition. When someone types Japanese, Chinese or Korean, the IME is open and Enter confirms the candidate, not the message. Check `event.nativeEvent.isComposing` and bail: ```tsx function onKeyDown(event: React.KeyboardEvent<HTMLTextAreaElement>) { if (event.key !== "Enter" || event.shiftKey) return if (event.nativeEvent.isComposing) return event.preventDefault() submit() } ``` Grow with the text, within limits. One line to start, up to about eight rows, then scroll. Animate the height change, and never through React state on every keystroke. Measure `scrollHeight` in a layout effect and set the height on the DOM node. Any setState in a native input listener will eventually drop or delay keys under load. Drafts survive a reload. Save the draft to `localStorage` keyed by chat id, debounced. People lose long prompts to accidental refreshes and never forgive you. Queue messages typed during a reply. If the model is still writing and the user sends another message, either disable sending or queue it and send when the stream ends. Silently dropping it is the worst option and it is the default. Attachments show progress and retry. Uploads fail. Show the failure on the attachment card with a retry, not as a toast that disappears. ## Streaming that reads well Models emit tokens in bursts. If you render exactly what arrives, text stutters: nothing, then twelve words, then nothing. Smooth it. Reveal characters at a steady pace that speeds up when the buffer grows, so you never fall far behind the stream but never stutter either. Markdown during streaming has its own trap: half-typed syntax. The model has written `bold` and not yet closed it, so your renderer shows literal asterisks for a frame, then bold text. Hold back incomplete inline syntax until it closes, or until the stream ends. Code blocks need the same care. Highlight incrementally and never re-highlight the whole block on every token. ## Stop, retry, edit and versions Stop should leave the partial reply on screen, with a visible "Stopped" marker so the user knows it is incomplete. Do not delete it. Retry on a failed reply is a button on the message, not a hidden gesture. Connect it to `regenerate()`. Edit an earlier message creates a branch. Both the old and new reply exist. Show a small `1 / 2` switcher on the message so the user can flip between versions. This is where a lot of homegrown chat UIs give up, and it is the feature people miss most from ChatGPT and Claude. Failed replies get a reason and a retry. "Something went wrong" with no action is a dead end. ## Scrolling Follow new tokens when the user is at the bottom. The moment they scroll up, stop following, and show a "jump to latest" button with a count of what they missed. When they jump, follow again. Loading older history at the top must not move the view. Measure the scroll height before and after you prepend, and adjust `scrollTop` by the difference in the same frame. If the user sends a message, scroll so their message pins to the top of the viewport and the reply streams below it. That is how the two big chat apps behave now and users expect it. ## Tool calls and approvals The AI SDK gives each tool part a state: `input-streaming`, `input-available`, `output-available`, `output-error`, and with human-in-the-loop, `approval-requested`, `approval-responded` and `output-denied`. Every state needs a look. Reads and searches can fold into a one-line summary. Edits, commands and errors should stay expanded. Approvals block the stream and need a clear Allow and Deny, plus a way to say "do this instead" that sends text back to the model as the denial reason. Show the result when it is useful. A file edit opens into a diff. A command opens into a terminal with the output. A search opens into results. A tool call that only says "Done" teaches users to ignore tool calls. ## Thinking and sources Reasoning parts should be collapsible and collapsed by default once the answer starts. While the model is still thinking, a live label that follows each step ("Searching docs", "Reading three files") is far more reassuring than a spinner. Citations belong next to the claims they support, inline, not in a list at the bottom nobody reads. ## Accessibility you cannot skip - New messages announce through a `role="log"` region, so screen reader users hear replies. - The stop button is reachable by keyboard and has a label. - Streaming text should not fire a hundred live-region announcements. Announce when the message completes, or at sentence boundaries. - Every icon-only button has `aria-label`. ## Putting it together If you want the pieces, shadcn/ui shipped AI Elements in October 2026: 21 patterns you copy into your project and compose yourself, including Chat, Prompt Input, Reasoning and Tool. Vercel's earlier AI Elements library is being deprecated at the end of November 2026 in favor of them. If you want the screens already assembled with the states above worked out, that is what the [HextaUI blocks](https://hextaui.com/blocks) are: a Chat Thread with stop, retry and versions, Tool Calls with every AI SDK state and approvals, Streaming and Markdown that never show half-typed syntax, and a Prompt Input that handles CJK input, uploads, queues and drafts. Prompt Input is free. The rest is a one-time purchase. All of it reads AI SDK message parts and none of it imports the SDK, so it works with any backend you can map. You can try the whole thing assembled as a chat app at [hextaui.com/blocks/hexta-ai](https://hextaui.com/blocks/hexta-ai) before installing anything. ## FAQ Do I need the Vercel AI SDK to use these patterns? No. The message-parts shape is the useful part. Any backend works once you map its output to parts. How do I handle Enter with an IME? Check `event.nativeEvent.isComposing` in your keydown handler and return early. Should streaming text update a live region on every token? No. Announce at completion or at sentence boundaries, or screen readers become unusable. What happens to a stopped reply? Keep the partial text and mark it as stopped. Never delete what the user has already read. ## Related - [How to build a one-page checkout in React and Next.js that survives declines and changed prices](https://hextaui.com/blog/one-page-checkout-react-nextjs) - A checkout form is easy. Declines, 3-D Secure, prices that change before Pay and payments that never answer are not. A one-page checkout in React and Next.js. - [Product variant picker UX in React: sold-out sizes, missing combinations and back-in-stock](https://hextaui.com/blog/product-variant-picker-react) - Colors and sizes look simple until stock lives on each combination. A React variant picker for sold-out sizes, missing combinations, photos, prices and the URL. - [Shopping cart UX in React: optimistic updates, undo and money in minor units](https://hextaui.com/blog/react-shopping-cart-optimistic-updates) - A React cart that feels instant and stays correct: money in minor units, optimistic quantities with rollback, merged requests, undo and free shipping progress. - [How to build an address form that works in every country, in React](https://hextaui.com/blog/international-address-form-react) - A US address form with a country dropdown is not international. Per-country fields, postal codes, autofill tokens, address search and errors in React. - [Building an e-commerce admin dashboard in Next.js: orders, refunds and inventory](https://hextaui.com/blog/ecommerce-admin-dashboard-nextjs) - The hard parts of a Next.js store admin: two order statuses, partial bulk failures, refund math that adds up to the cent, inventory adjustments and discounts. ---  # Vercel's AI Elements is being deprecated. Here are the alternatives for shadcn/ui AI chat UI > Vercel's AI Elements is deprecated at the end of November 2026. What replaces it, what to do with code you copied, and five shadcn/ui AI chat options compared. Canonical: https://hextaui.com/blog/ai-elements-deprecated-alternatives Last updated: 2026-10-16 By Preet Suthar · 2026-10-16 · 5 min read If you built an AI chat with Vercel's AI Elements this year, the repository now carries a notice: the library will be deprecated at the end of November 2026, replaced by AI Elements from shadcn/ui. This post covers what that means for your code, what the replacement is, and the other options if you are starting an AI chat UI with shadcn/ui in late 2026. I maintain one of those options, [HextaUI](https://hextaui.com), so I will say where it fits and where it does not. ## First: your code keeps working AI Elements was a shadcn-style registry. The components were copied into your project. There is no package to stop receiving updates, so nothing breaks on 1 December. The deprecation means no new components and no fixes from Vercel, and the docs will eventually point elsewhere. You have time. Do not rush a migration this week. ## What replaces it In October 2026 shadcn/ui published its own [AI Elements](https://ui.shadcn.com/docs/ai-elements): 21 patterns for agentic interfaces built from shadcn/ui components. Chat, Prompt Input, Reasoning, Tool, Plan, Subagent and more. Each pattern page shows how to render it from AI SDK message parts. There is no package. You copy each pattern in. They ship alongside two new components, Trace and Code Block, that work across Base UI, React Aria and Radix. Migration from the Vercel library is meant to be low-friction. Export names and props are kept where the pattern was rebuilt, and each pattern page includes a migration prompt you can hand to an AI coding agent. Elements that were not rebuilt are not covered, so check the list against what you use. ## The honest difference between pieces and screens Every option below falls into one of two camps, and knowing which you want saves a week. Pieces give you a Message, a Prompt Input, a Tool component. You design the screen and decide what happens when a reply fails, when a stream is stopped, when a tool needs approval, when an upload dies. Both versions of AI Elements, and prompt-kit, are pieces. Screens give you the chat thread, composer, tool call list and settings pages with those decisions already made. You wire data in and restyle with your theme tokens. HextaUI's blocks and complete apps like Vercel's AI Chatbot template are screens. Pieces are free and flexible. Screens are faster and opinionated. Neither is wrong. ## Five options compared ### 1. AI Elements from shadcn/ui Free, MIT, maintained by the shadcn team, built for Base UI, React Aria and Radix. Pieces, not screens. The natural default if you want to compose your own and stay on the most-used registry. New as of October 2026, so expect the pattern list to grow and the rough edges to be sanded over the next few months. ### 2. prompt-kit Free, MIT, installs with the shadcn CLI. Prompt Input, Message, Reasoning, Chain of Thought, Tool, File Upload and example blocks including a chat app with a history sidebar. Pieces, with good examples. Built on Radix, so a Base UI project carries both primitive layers while you use it. ### 3. assistant-ui Free, MIT, with an optional paid cloud for saved threads. This one is different in kind: it is a chat framework with its own runtime that manages the conversation, plus headless primitives and styled components that read from it. Adapters for the AI SDK, LangGraph, LangChain, AG-UI and others. Pick it if you want the runtime to own the chat state. Skip it if your state already lives in `useChat` or your own store and you do not want anything wrapping your app. ### 4. shadcn-chatbot-kit and the AI Chatbot template Blazity's shadcn-chatbot-kit is a smaller set of chatbot components. Vercel's AI Chatbot is a complete Next.js app with sign-in and a database, which is the canonical reference if you want to see every piece wired. Both are useful to read even if you do not adopt them. ### 5. HextaUI blocks Screens. A Chat Thread where failed replies offer Try again, stopped replies say so, and edits and retries become versions you can switch between. Tool Calls with every AI SDK tool state including approvals with a "do this instead" reason. Streaming and Markdown that never show half-typed syntax. A Prompt Input that is safe with Japanese and Chinese input, shows upload progress and retry, queues messages typed during a reply and keeps drafts across reloads. Plus the screens around a chat product: settings, models, API keys, billing, team, security. The components underneath are free and MIT. The AI blocks are HextaUI Pro, a one-time payment with every later block included, and Prompt Input is free. Built on Base UI, reads AI SDK message parts without importing the SDK. Not for you if you want everything free, or if you want Radix. ## At a glance | | Camp | Price | Primitives | AI SDK | |---|---|---|---|---| | AI Elements (shadcn/ui) | Pieces | Free | Base UI, React Aria, Radix | Used in examples | | AI Elements (Vercel) | Pieces | Free | Radix | Required by setup | | prompt-kit | Pieces | Free | Radix | Optional | | assistant-ui | Runtime | Free, paid cloud | Own | Adapter | | HextaUI | Screens | Components free, blocks paid once | Base UI | Optional, same parts shape | ## How to decide - You are starting fresh and want to compose your own: AI Elements from shadcn/ui. - You already have Vercel's AI Elements in your tree: keep it until you need something new, then move pattern by pattern using the migration prompts. - You want a runtime to manage threads, branching and persistence for you: assistant-ui. - You want the chat and the product screens around it done, with the failure states handled, and you are fine paying once: HextaUI. All of these copy source into your project and use the shadcn/ui theme tokens, so you can mix them one screen at a time. The one caution is primitives: mixing a Radix-based kit into a Base UI project works, but you ship both. I keep a more detailed comparison with the full piece-by-piece mapping at [hextaui.com/compare/ai-elements](https://hextaui.com/compare/ai-elements), and a seven-way look at [shadcn AI chat templates](https://hextaui.com/compare/shadcn-ai-chat-templates). ## FAQ When exactly is Vercel's AI Elements deprecated? The repository says the end of November 2026. Will my existing AI Elements components break? No. They live in your repository. They stop receiving updates. Is the new AI Elements a package? No. It is a set of patterns you copy in with the shadcn CLI, the same model as shadcn/ui itself. Can I use HextaUI blocks without the Vercel AI SDK? Yes. They take messages as props in the AI SDK's parts shape, and do not import the SDK. ## Related - [How to build a one-page checkout in React and Next.js that survives declines and changed prices](https://hextaui.com/blog/one-page-checkout-react-nextjs) - A checkout form is easy. Declines, 3-D Secure, prices that change before Pay and payments that never answer are not. A one-page checkout in React and Next.js. - [Product variant picker UX in React: sold-out sizes, missing combinations and back-in-stock](https://hextaui.com/blog/product-variant-picker-react) - Colors and sizes look simple until stock lives on each combination. A React variant picker for sold-out sizes, missing combinations, photos, prices and the URL. - [Shopping cart UX in React: optimistic updates, undo and money in minor units](https://hextaui.com/blog/react-shopping-cart-optimistic-updates) - A React cart that feels instant and stays correct: money in minor units, optimistic quantities with rollback, merged requests, undo and free shipping progress. - [How to build an address form that works in every country, in React](https://hextaui.com/blog/international-address-form-react) - A US address form with a country dropdown is not international. Per-country fields, postal codes, autofill tokens, address search and errors in React. - [Building an e-commerce admin dashboard in Next.js: orders, refunds and inventory](https://hextaui.com/blog/ecommerce-admin-dashboard-nextjs) - The hard parts of a Next.js store admin: two order statuses, partial bulk failures, refund math that adds up to the cent, inventory adjustments and discounts. ---  # How to build a shadcn/ui registry that Claude Code and Cursor can actually use > A shadcn registry is half the job in 2026. Namespaces, Markdown docs at .md URLs, llms.txt, an MCP server and private registries, so AI agents install it right. Canonical: https://hextaui.com/blog/agent-ready-shadcn-registry Last updated: 2026-10-16 By Preet Suthar · 2026-10-16 · 5 min read Most shadcn/ui components are now installed by an AI coding agent, not a person typing the command. If you publish a registry, the agent is your user. It needs to find your components, read their props without guessing, and run the right install command. A registry that only works for humans clicking through a docs site is a registry that gets misused. I run [HextaUI](https://hextaui.com), a shadcn/ui registry, and I spent a chunk of this year making it work for Claude Code, Cursor and the shadcn MCP server. This is everything that turned out to matter, in the order I would do it again. ## 1. Ship a registry that passes validation Start with the basics. Every item is a JSON file that follows the registry schema, with `name`, `type`, `files`, `dependencies` and `registryDependencies`. Put the index at a stable URL and every item at a predictable one: ``` https://your-site.com/r/registry.json https://your-site.com/r/button.json https://your-site.com/r/all.json ``` Run `shadcn build` to generate them from a `registry.json` source, and validate before you deploy. The CLI gained a registry validate step in May 2026. A registry that fails validation fails silently for agents, who will then write the component by hand and get it wrong. Two details that make a real difference: - `registryDependencies` with full URLs. When your Dialog depends on your Button, point to `https://your-site.com/r/button.json`, not `button`, or the CLI pulls the shadcn/ui Button instead. - An `all.json` item that depends on everything. Agents asked to "set up the design system" will reach for it. ## 2. Register a namespace Since the registry namespace feature landed, a user adds this to `components.json`: ```json { "registries": { "@hextaui": "https://hextaui.com/r/{name}.json" } } ``` And then installs with a short name: ```bash npx shadcn@latest add @hextaui/dialog ``` Document this snippet on your installation page and in your `llms.txt`. The short form is what the shadcn MCP server searches across, so a registry without a namespace is invisible to the one tool most agents use to browse registries. If the registry is private, the object form takes headers with environment variables that the CLI expands and never logs: ```json { "registries": { "@acme-pro": { "url": "https://acme.com/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${ACME_TOKEN}" } } } } ``` ## 3. Give every docs page a Markdown twin Agents fetch HTML badly. They fetch Markdown well. Make every docs URL answer at `.md` with the same content: description, install command, full source, usage, examples, keyboard support and the API table. ``` https://hextaui.com/docs/button -> HTML for people https://hextaui.com/docs/button.md -> Markdown for agents ``` Do not hand-write the Markdown. Generate it from the same source as the page so the two never drift. On HextaUI the `.md` route walks the page's React tree and serializes it, so adding an example to the page adds it to the Markdown for free. The API reference matters most here. An agent that can read a props table does not hallucinate a `size="xl"` that does not exist. ## 4. Publish llms.txt and llms-full.txt `llms.txt` is a Markdown index at your site root: what the project is, when to use it, when not to, how to install, and one line per docs page with its `.md` link. `llms-full.txt` is every docs page concatenated, for agents that want to load everything once. The "when not to use it" section is the part people skip and the part that saves you support tickets. If your registry is React and Tailwind only, say so, or an agent will try to install it into a Vue project. Keep the install command in the first ten lines. Agents read the top. ## 5. Run an MCP server, read-only, no key The shadcn CLI has its own MCP server (`npx shadcn@latest mcp`) that searches any registry in `components.json`. That covers installs. It does not cover docs, keyboard maps or examples. So I run a second one at `https://hextaui.com/mcp`, Streamable HTTP, read-only, no API key, with five tools: `search_docs`, `get_component`, `get_component_api`, `get_examples` and `get_install_command`. Claude Code connects with one line: ```bash claude mcp add --transport http hextaui https://hextaui.com/mcp ``` Cursor and VS Code take the same URL in their MCP config. Once connected, "add a HextaUI combobox with async results" turns into a docs search, an API read and the right install command, with no guessing in between. Make it discoverable too. Publish a server card at `/.well-known/mcp/server-card.json` and a `server.json` in the MCP registry format. Agents and the tools around them are starting to look there first. ## 6. Describe the HTTP surface with OpenAPI and real errors Everything above is also plain HTTP, and agents increasingly call HTTP directly. Publish an `openapi.json` with operation ids and typed responses. Return errors as RFC 9457 `application/problem+json` with a `resolution` field that says what to do next: ```json { "type": "https://hextaui.com/docs/api#not-found", "title": "Component not found", "status": 404, "detail": "No component named 'modal'.", "resolution": "Try 'dialog' or 'alert-dialog'. The catalog is at /mcp/index.json." } ``` An agent that gets a 404 with a hint recovers. An agent that gets an HTML error page writes the component from memory. ## 7. Ship a skill file Claude Code and a growing list of agents read `SKILL.md` files that explain how to use a tool. Put one at `/.well-known/agent-skills/<name>/SKILL.md`: how to find a component, read its docs, and install it, with the exact commands. It is a page of Markdown and it is the highest-leverage page on the site. ## 8. Test with the agents, not with yourself Open a fresh Next.js project in Claude Code with your MCP server connected and no other context. Ask it to "add a date picker from <your registry> with a range and a disabled weekend rule". Watch what it does. Every wrong guess is a gap in your `.md` docs or your `llms.txt`. Then do the same in Cursor with only `llms.txt` and no MCP. Then with nothing but the URL. The registry should degrade gracefully through all three. ## What this gets you An agent with the MCP server or the `.md` docs connected reads the props table instead of guessing it, runs the install command instead of rewriting the component, and installs the dependencies in the right order. The registry side of HextaUI was about a week of work. The agent side took longer, and it is the part that made the registry usable by the people who now do most of the installing. If you want to see all of it live: [hextaui.com/llms.txt](https://hextaui.com/llms.txt), any docs page with `.md` appended, the [MCP docs](https://hextaui.com/docs/mcp), and the [API docs](https://hextaui.com/docs/api) with the OpenAPI spec. ## FAQ Do I need my own MCP server if the shadcn CLI has one? The shadcn MCP covers search and install across registries in `components.json`. Your own server covers docs, APIs and examples. Most registries benefit from both. Should the MCP server require an API key? Not for public docs. Every key you require is an agent that gives up. Keep auth for private items and use bearer tokens through `components.json` headers. How do I generate the Markdown docs without duplicating content? Render the same component tree the page uses and serialize it to Markdown. One source, two formats. What goes in llms.txt? A description, when to use and when not to, the install command, the namespace snippet, and one line per docs page linking to its `.md`. ## Related - [How to build a one-page checkout in React and Next.js that survives declines and changed prices](https://hextaui.com/blog/one-page-checkout-react-nextjs) - A checkout form is easy. Declines, 3-D Secure, prices that change before Pay and payments that never answer are not. A one-page checkout in React and Next.js. - [Product variant picker UX in React: sold-out sizes, missing combinations and back-in-stock](https://hextaui.com/blog/product-variant-picker-react) - Colors and sizes look simple until stock lives on each combination. A React variant picker for sold-out sizes, missing combinations, photos, prices and the URL. - [Shopping cart UX in React: optimistic updates, undo and money in minor units](https://hextaui.com/blog/react-shopping-cart-optimistic-updates) - A React cart that feels instant and stays correct: money in minor units, optimistic quantities with rollback, merged requests, undo and free shipping progress. - [How to build an address form that works in every country, in React](https://hextaui.com/blog/international-address-form-react) - A US address form with a country dropdown is not international. Per-country fields, postal codes, autofill tokens, address search and errors in React. - [Building an e-commerce admin dashboard in Next.js: orders, refunds and inventory](https://hextaui.com/blog/ecommerce-admin-dashboard-nextjs) - The hard parts of a Next.js store admin: two order statuses, partial bulk failures, refund math that adds up to the cent, inventory adjustments and discounts. ---  # HextaUI Research > Original statistics computed from data HextaUI collects itself: shadcn/ui component source and the HextaUI Pro block catalog. Every number states its sample and method. Canonical: https://hextaui.com/research Last updated: 2026-10-26 - [shadcn/ui Component Statistics 2026: 62 Analyzed](https://hextaui.com/research/shadcn-ui-components) (updated 2026-10-26): 62 shadcn/ui components measured from source: median 97 lines, 24% use cva variants, 35% depend on another component, Button is the most reused. - [UI Component Usage Statistics 2026: 49 Blocks Analyzed](https://hextaui.com/research/ui-component-usage) (updated 2026-10-22): 49 HextaUI Pro blocks: Button is in 94%, the median block imports 9 components, 56 of 65 components are used. ---  # shadcn/ui Component Statistics 2026: 62 Analyzed > How big shadcn/ui components are, how many use variants and which ones the others are built from, measured from the published source of 62 components on October 26, 2026. Canonical: https://hextaui.com/research/shadcn-ui-components Last updated: 2026-10-26 Updated October 26, 2026. Sample: 62 components. Source: shadcn/ui registry (https://ui.shadcn.com/r/index.json). ## Key findings - The median shadcn/ui component is 97 lines of source code, measured across 62 components in the base-vega style; together they come to 8,575 lines. Denominator: all 62 analyzed components. [Link](https://hextaui.com/research/shadcn-ui-components#finding-median-size) - Sidebar is the largest shadcn/ui component at 730 lines, followed by Chart (372) and Questionnaire (332). 17 of the 62 components (27%) are 200 lines or longer. Denominator: all 62 analyzed components. [Link](https://hextaui.com/research/shadcn-ui-components#finding-largest-components) - 15 of the 62 shadcn/ui components (24%) define style variants with class-variance-authority (cva); the other 47 have no cva variants. Denominator: all 62 analyzed components. [Link](https://hextaui.com/research/shadcn-ui-components#finding-cva-variants) - 22 of the 62 shadcn/ui components (35%) install at least one other shadcn/ui component as a registry dependency; the other 40 stand alone. Denominator: all 62 analyzed components. [Link](https://hextaui.com/research/shadcn-ui-components#finding-registry-dependencies) - Button is the most reused building block: 14 of the 62 components (23%) depend on it, followed by Separator (4). Denominator: all 62 analyzed components. A component counts once per dependency it lists. [Link](https://hextaui.com/research/shadcn-ui-components#finding-most-reused) - The median shadcn/ui component exports 4.5 parts; 13 of the 62 components (21%) export a single part and 12 (19%) export 10 or more. Denominator: all 62 analyzed components. A part is an exported function component. [Link](https://hextaui.com/research/shadcn-ui-components#finding-parts-per-component) - Components that build on other shadcn/ui components are larger: a median of 208.5 lines for the 22 that do, against 67.5 for the 40 that stand alone. Two groups: 22 components with registry dependencies and 40 without. Differences under 10% are reported as about the same. [Link](https://hextaui.com/research/shadcn-ui-components#finding-dependencies-and-size) Not reported because the sample is too small: - Size of components with and without cva variants: only 15 components are in the smaller group, below the 20-row minimum. ## Breakdowns ### Components by size Lines of source code per component. Share of all 62 analyzed components. | Lines of source | Components | Share | | --- | ---: | ---: | | Under 50 lines | 14 | 23% | | 50–99 lines | 17 | 27% | | 100–199 lines | 14 | 23% | | 200–399 lines | 16 | 26% | | 400 lines or more | 1 | 2% | ### Components by number of parts Exported function components per registry item. Share of all 62 analyzed components. | Exported parts | Components | Share | | --- | ---: | ---: | | 1 part | 13 | 21% | | 2–4 parts | 18 | 29% | | 5–9 parts | 19 | 31% | | 10 parts or more | 12 | 19% | ### Most reused components How many of the 62 analyzed components list each one as a registry dependency. | Component | Components that depend on it | Share | | --- | ---: | ---: | | Button | 14 | 23% | | Separator | 4 | 6% | | Input | 2 | 3% | | Input group | 2 | 3% | | Card | 1 | 2% | | Collapsible | 1 | 2% | | Dialog | 1 | 2% | | Dropdown menu | 1 | 2% | | Label | 1 | 2% | | Sheet | 1 | 2% | | Skeleton | 1 | 2% | | Textarea | 1 | 2% | | Toggle | 1 | 2% | | Tooltip | 1 | 2% | | use-highlighted-code | 1 | 2% | | use-mobile | 1 | 2% | ### Every component Ordered by lines of source code, largest first. | Component | Lines | Parts | cva variant groups | Registry dependencies | | --- | ---: | ---: | ---: | --- | | Sidebar | 730 | 23 | 2 | Button, Input, Separator, Sheet, Skeleton, Tooltip, use-mobile | | Chart | 372 | 3 | 0 | Card | | Questionnaire | 332 | 15 | 0 | Button | | Combobox | 328 | 14 | 0 | Button, Input group | | Menubar | 296 | 16 | 0 | Dropdown menu | | Context menu | 291 | 15 | 0 | None | | Dropdown menu | 291 | 15 | 0 | None | | Toast | 278 | 10 | 0 | Button | | Code block | 259 | 8 | 2 | Button, use-highlighted-code | | Carousel | 256 | 5 | 0 | Button | | Calendar | 245 | 2 | 0 | Button | | Field | 238 | 10 | 1 | Label, Separator | | Select | 228 | 9 | 0 | None | | Drawer | 224 | 11 | 0 | None | | Command | 210 | 9 | 0 | Dialog, Input group | | Attachment | 207 | 9 | 3 | Button | | Item | 201 | 10 | 3 | Separator | | Alert dialog | 187 | 12 | 0 | Button | | Navigation menu | 176 | 8 | 0 | None | | Trace | 167 | 8 | 0 | Collapsible | | Dialog | 162 | 10 | 0 | Button | | Input group | 158 | 6 | 2 | Button, Input, Textarea | | Pagination | 151 | 7 | 0 | Button | | Sheet | 140 | 8 | 0 | Button | | Breadcrumb | 137 | 7 | 0 | None | | Message scroller | 136 | 6 | 0 | Button | | Bubble | 127 | 4 | 3 | None | | Table | 115 | 8 | 0 | None | | Avatar | 108 | 6 | 0 | None | | Empty | 103 | 6 | 1 | None | | Card | 102 | 7 | 0 | None | | Input OTP | 92 | 4 | 0 | None | | Message | 91 | 6 | 0 | None | | Popover | 89 | 6 | 0 | None | | Toggle group | 89 | 2 | 0 | Toggle | | Accordion | 88 | 4 | 0 | None | | Button group | 87 | 3 | 1 | Separator | | Progress | 82 | 5 | 0 | None | | Tabs | 81 | 4 | 1 | None | | Alert | 75 | 4 | 1 | None | | Marker | 70 | 3 | 1 | None | | Native select | 70 | 3 | 0 | None | | Tooltip | 65 | 4 | 0 | None | | Button | 57 | 1 | 2 | None | | Scroll area | 54 | 2 | 0 | None | | Badge | 51 | 1 | 1 | None | | Slider | 51 | 1 | 0 | None | | Hover card | 50 | 3 | 0 | None | | Resizable | 49 | 3 | 0 | None | | Toggle | 44 | 1 | 2 | None | | Radio group | 37 | 2 | 0 | None | | Checkbox | 34 | 1 | 0 | None | | Switch | 31 | 1 | 0 | None | | Kbd | 26 | 2 | 0 | None | | Separator | 24 | 1 | 0 | None | | Aspect ratio | 22 | 1 | 0 | None | | Spinner | 22 | 1 | 0 | None | | Collapsible | 21 | 3 | 0 | None | | Input | 19 | 1 | 0 | None | | Label | 19 | 1 | 0 | None | | Textarea | 17 | 1 | 0 | None | | Skeleton | 13 | 1 | 0 | None | ## Methodology - Source: the shadcn/ui registry index (https://ui.shadcn.com/r/index.json). Every item of type registry:ui, 65 in total, was fetched from https://ui.shadcn.com/r/styles/base-vega/<name>.json on October 26, 2026. - Included: 62 of the 65 items. Excluded: Direction, because its source exports no function components the parser can read (a re-export or an arrow-function wrapper); Form, because it ships no source code in this style; Sonner, because its source exports no function components the parser can read (a re-export or an arrow-function wrapper). - Lines: every line of the item's published files joined together, trailing blank lines removed. Comments and blank lines inside the file count. - Parts: exported functions whose names start with a capital letter. Components written as arrow functions are not counted. - cva variant groups: keys of the variants object in each cva() call. Registry dependencies: the item's registryDependencies list. - Not reported: npm dependencies, because the base-vega style declares shared packages such as @base-ui/react once for the whole style rather than on every item. - One style only: the base-vega style, which is built on Base UI. Radix-based styles may differ in size. - Every value is computed from published code; none is entered by hand or by users. - Refreshed when the snapshot is re-fetched with pnpm shadcn:snapshot. The date on this page is the fetch date. - Percentages are rounded to the nearest whole number, so a table can add up to 99% or 101%. A median of an even count is the mean of the middle two values. - A finding that compares two groups needs at least 20 components in each group. ## Frequently asked questions ### How many components does shadcn/ui have? The shadcn/ui registry listed 65 UI components (items of type registry:ui) on October 26, 2026. HextaUI fetched every one from the base-vega style and measured the 62 that ship readable component source. [Link](https://hextaui.com/research/shadcn-ui-components#faq-how-many-components) ### What is the largest shadcn/ui component? Sidebar is the largest shadcn/ui component at 730 lines of source code in the base-vega style, measured on October 26, 2026. The median component is 97 lines. [Link](https://hextaui.com/research/shadcn-ui-components#faq-largest-component) ### How many lines of code is a typical shadcn/ui component? The median shadcn/ui component is 97 lines of source code, across 62 components in the base-vega style measured on October 26, 2026. 17 of the 62 components (27%) are 200 lines or longer. [Link](https://hextaui.com/research/shadcn-ui-components#faq-typical-size) ### How many shadcn/ui components use cva variants? 15 of the 62 shadcn/ui components (24%) define variants with class-variance-authority (cva), measured on October 26, 2026. They include Alert, Attachment, Badge, Bubble and Button. [Link](https://hextaui.com/research/shadcn-ui-components#faq-cva-variants) ### Which shadcn/ui component do other components depend on most? Button. 14 of the 62 shadcn/ui components (23%) list it as a registry dependency, measured on October 26, 2026. [Link](https://hextaui.com/research/shadcn-ui-components#faq-most-reused) ## Cite this research HextaUI. “shadcn/ui Component Statistics 2026: 62 Analyzed.” https://hextaui.com/research/shadcn-ui-components. Updated October 2026. ## Related - [All research](https://hextaui.com/research) - [HextaUI vs shadcn/ui](https://hextaui.com/compare/shadcn-ui) - [HextaUI components](https://hextaui.com/components) ---  # UI Component Usage Statistics 2026: 49 Blocks Analyzed > Which UI components product screens are built from, counted from the source of 49 HextaUI Pro blocks (23 e-commerce, 16 AI and 10 settings) on October 22, 2026. Canonical: https://hextaui.com/research/ui-component-usage Last updated: 2026-10-22 Updated October 22, 2026. Sample: 49 blocks. Source: HextaUI Pro blocks (https://hextaui.com/blocks). ## Key findings - Button is the most used UI component: 46 of the 49 HextaUI Pro blocks (94%) import it, followed by Badge (27) and Input (20). Denominator: all 49 blocks. [Link](https://hextaui.com/research/ui-component-usage#finding-most-used) - The median HextaUI Pro block imports 9 different UI components, from 2 in Price, Product Gallery, Streaming and Variant Picker to 23 in Order Detail. Denominator: all 49 blocks. Each component counts once per block. [Link](https://hextaui.com/research/ui-component-usage#finding-components-per-block) - The 49 blocks use 56 of the 65 HextaUI components (86%); 9 are never imported directly by a block: Aspect ratio, Carousel, Data table, Item, Menubar, Navigation menu, Pagination, Scroll area and Video player. Denominator: all 65 components in the HextaUI library. [Link](https://hextaui.com/research/ui-component-usage#finding-library-coverage) - Apart from buttons, data display components are the most common kind of component: 39 of the 49 blocks (80%) use at least one. Chat components are the least common, in 4 (8%). Denominator: all 49 blocks. Kinds follow the categories in the HextaUI docs, leaving out kinds with fewer than 3 components; a block counts once per kind. [Link](https://hextaui.com/research/ui-component-usage#finding-component-kinds) - E-commerce blocks import more components than the rest: a median of 10 for the 23 e-commerce blocks, against 7.5 for the other 26. Two groups: 23 e-commerce blocks and 26 others. Differences under 10% are reported as about the same. [Link](https://hextaui.com/research/ui-component-usage#finding-category-comparison) Not reported because the sample is too small: - Findings for single categories with fewer than 20 blocks: AI (16) and Settings (10). They appear in the tables only. ## Breakdowns ### Every component, ranked by use How many of the 49 blocks import each HextaUI component. Ties are listed A to Z. | Rank | Component | Blocks | Share | | ---: | --- | ---: | ---: | | 1 | Button | 46 | 94% | | 2 | Badge | 27 | 55% | | 3 | Input | 20 | 41% | | 4 | Collapsible | 18 | 37% | | 5 | Input group | 18 | 37% | | 6 | Spinner | 18 | 37% | | 7 | Field | 17 | 35% | | 8 | Tooltip | 17 | 35% | | 9 | Dropdown menu | 15 | 31% | | 10 | Kbd | 15 | 31% | | 11 | Number flow | 15 | 31% | | 12 | Skeleton | 14 | 29% | | 13 | Checkbox | 13 | 27% | | 14 | Empty | 13 | 27% | | 15 | Popover | 13 | 27% | | 16 | Dialog | 12 | 24% | | 17 | Select | 12 | 24% | | 18 | Switch | 12 | 24% | | 19 | Toast | 12 | 24% | | 20 | Toggle group | 12 | 24% | | 21 | Alert dialog | 9 | 18% | | 22 | Avatar | 9 | 18% | | 23 | Card | 9 | 18% | | 24 | Sheet | 8 | 16% | | 25 | Separator | 7 | 14% | | 26 | Textarea | 7 | 14% | | 27 | Progress | 6 | 12% | | 28 | Radio group | 6 | 12% | | 29 | Alert | 5 | 10% | | 30 | Table | 5 | 10% | | 31 | Slider | 4 | 8% | | 32 | Breadcrumb | 3 | 6% | | 33 | Bubble | 3 | 6% | | 34 | Combobox | 3 | 6% | | 35 | Message | 3 | 6% | | 36 | Sidebar | 3 | 6% | | 37 | Toggle | 3 | 6% | | 38 | Attachment | 2 | 4% | | 39 | Button group | 2 | 4% | | 40 | Chart | 2 | 4% | | 41 | Command | 2 | 4% | | 42 | Date picker | 2 | 4% | | 43 | Drawer | 2 | 4% | | 44 | Hover card | 2 | 4% | | 45 | Input OTP | 2 | 4% | | 46 | Tabs | 2 | 4% | | 47 | Tree | 2 | 4% | | 48 | Accordion | 1 | 2% | | 49 | Calendar | 1 | 2% | | 50 | Context menu | 1 | 2% | | 51 | Label | 1 | 2% | | 52 | Marker | 1 | 2% | | 53 | Message scroller | 1 | 2% | | 54 | Native select | 1 | 2% | | 55 | Questionnaire | 1 | 2% | | 56 | Resizable | 1 | 2% | | 57 | Aspect ratio | 0 | 0% | | 58 | Carousel | 0 | 0% | | 59 | Data table | 0 | 0% | | 60 | Item | 0 | 0% | | 61 | Menubar | 0 | 0% | | 62 | Navigation menu | 0 | 0% | | 63 | Pagination | 0 | 0% | | 64 | Scroll area | 0 | 0% | | 65 | Video player | 0 | 0% | ### Blocks by kind of component Share of all 49 blocks that use at least one component of each kind. | Kind of component | Components of this kind | Blocks | Share | | --- | ---: | ---: | ---: | | Buttons and actions | 4 | 46 | 94% | | Data display components | 10 | 39 | 80% | | Feedback components | 6 | 39 | 80% | | Overlays | 11 | 37 | 76% | | Form controls | 16 | 31 | 63% | | Layout components | 7 | 22 | 45% | | Navigation components | 5 | 7 | 14% | | Chat components | 5 | 4 | 8% | ### Blocks by category Categories with fewer than 20 blocks are shown here but get no findings of their own. | Block category | Blocks | Median components per block | | --- | ---: | ---: | | E-commerce | 23 | 10 | | AI | 16 | 6.5 | | Settings | 10 | 10.5 | ### Blocks by number of components Share of all 49 blocks. | Components imported | Blocks | Share | | --- | ---: | ---: | | 1–4 components | 9 | 18% | | 5–9 components | 17 | 35% | | 10–14 components | 16 | 33% | | 15 components or more | 7 | 14% | ### Every block Ordered by the number of components imported, most first. | Block | Category | Components | Imports | | --- | --- | ---: | --- | | Order Detail | E-commerce | 23 | Alert, Alert dialog, Avatar, Badge, Button, Button group, Card, Collapsible, Dropdown menu, Field, Input, Input group, Kbd, Select, Separator, Sheet, Skeleton, Spinner, Switch, Textarea, Toast, Toggle group, Tooltip | | Discount Builder | E-commerce | 22 | Avatar, Badge, Button, Card, Checkbox, Collapsible, Combobox, Date picker, Dialog, Dropdown menu, Field, Input, Input group, Kbd, Number flow, Popover, Progress, Separator, Spinner, Switch, Toggle group, Tooltip | | Product Editor | E-commerce | 20 | Alert dialog, Badge, Breadcrumb, Button, Card, Checkbox, Collapsible, Combobox, Dialog, Dropdown menu, Field, Input, Input group, Number flow, Popover, Progress, Select, Switch, Textarea, Toast | | Orders Table | E-commerce | 19 | Alert dialog, Badge, Button, Button group, Checkbox, Dropdown menu, Empty, Input, Input group, Kbd, Number flow, Popover, Radio group, Select, Skeleton, Table, Tabs, Toast, Tooltip | | Commerce Dashboard | E-commerce | 17 | Avatar, Badge, Breadcrumb, Button, Command, Dialog, Dropdown menu, Empty, Input group, Kbd, Number flow, Popover, Progress, Select, Sidebar, Table, Toast | | API keys | Settings | 16 | Alert dialog, Badge, Button, Checkbox, Collapsible, Date picker, Dialog, Dropdown menu, Empty, Field, Input, Select, Skeleton, Toast, Toggle group, Tooltip | | Refund | E-commerce | 15 | Alert, Alert dialog, Badge, Button, Checkbox, Collapsible, Empty, Field, Input group, Number flow, Select, Separator, Sheet, Switch, Textarea | | Billing | Settings | 14 | Alert, Alert dialog, Badge, Button, Chart, Collapsible, Dialog, Field, Input, Input group, Skeleton, Slider, Switch, Table | | Inventory | E-commerce | 14 | Badge, Button, Checkbox, Drawer, Empty, Input group, Kbd, Number flow, Popover, Select, Sheet, Skeleton, Table, Toggle group | | Product Filters | E-commerce | 14 | Badge, Button, Checkbox, Collapsible, Empty, Input group, Number flow, Progress, Radio group, Select, Sheet, Slider, Switch, Toggle group | | Diff Review | AI | 13 | Avatar, Button, Card, Dropdown menu, Empty, Input group, Kbd, Number flow, Popover, Spinner, Toggle group, Tooltip, Tree | | Sales Overview | E-commerce | 13 | Avatar, Badge, Button, Calendar, Card, Chart, Number flow, Popover, Select, Skeleton, Table, Toggle group, Tooltip | | Team | Settings | 13 | Alert dialog, Avatar, Badge, Button, Collapsible, Dropdown menu, Empty, Input, Input group, Label, Switch, Textarea, Toast | | Artifact | AI | 12 | Button, Drawer, Dropdown menu, Kbd, Number flow, Resizable, Skeleton, Spinner, Tabs, Toast, Toggle, Tooltip | | Chat Sidebar | AI | 12 | Avatar, Button, Collapsible, Command, Context menu, Dropdown menu, Hover card, Kbd, Sidebar, Spinner, Toast, Tooltip | | Reviews | E-commerce | 12 | Badge, Button, Dialog, Empty, Field, Input, Input group, Number flow, Select, Textarea, Toggle, Toggle group | | Models | Settings | 11 | Badge, Button, Collapsible, Dialog, Dropdown menu, Field, Input, Input group, Switch, Toggle group, Tooltip | | Order Status | E-commerce | 11 | Badge, Button, Card, Checkbox, Collapsible, Field, Input, Radio group, Select, Separator, Textarea | | Profile | Settings | 11 | Avatar, Badge, Button, Dialog, Field, Input, Input group, Input OTP, Slider, Spinner, Switch | | Chat Thread | AI | 10 | Attachment, Bubble, Button, Kbd, Marker, Message, Message scroller, Popover, Toast, Tooltip | | Notifications | Settings | 10 | Alert dialog, Badge, Button, Checkbox, Dialog, Field, Input, Select, Switch, Toggle group | | Payment | E-commerce | 10 | Alert, Button, Checkbox, Dialog, Field, Input, Input group, Radio group, Separator, Spinner | | Security | Settings | 10 | Alert dialog, Badge, Button, Checkbox, Dialog, Field, Input, Input group, Input OTP, Skeleton | | Address Form | E-commerce | 9 | Badge, Button, Combobox, Field, Input, Input group, Native select, Radio group, Spinner | | Prompt Input | AI | 9 | Attachment, Button, Dialog, Dropdown menu, Kbd, Number flow, Popover, Switch, Tooltip | | Shipping Methods | E-commerce | 9 | Badge, Button, Empty, Field, Input, Popover, Radio group, Skeleton, Toggle group | | Storefront | E-commerce | 8 | Accordion, Breadcrumb, Button, Empty, Input, Separator, Sheet, Toast | | Tool Calls | AI | 8 | Button, Card, Collapsible, Kbd, Questionnaire, Spinner, Textarea, Tree | | Code Block | AI | 7 | Badge, Button, Card, Kbd, Spinner, Toggle, Tooltip | | Settings | Settings | 7 | Button, Collapsible, Dropdown menu, Empty, Field, Input group, Skeleton | | Thinking | AI | 7 | Avatar, Badge, Bubble, Collapsible, Hover card, Message, Spinner | | Cart | E-commerce | 6 | Badge, Button, Empty, Number flow, Sheet, Spinner | | Checkout | E-commerce | 6 | Badge, Button, Checkbox, Field, Input, Spinner | | Product Card | E-commerce | 6 | Badge, Button, Sheet, Skeleton, Spinner, Toast | | Subagents | AI | 6 | Badge, Button, Collapsible, Progress, Spinner, Tooltip | | Test Results | AI | 6 | Button, Collapsible, Number flow, Progress, Spinner, Toggle group | | Agent Todos | AI | 5 | Button, Collapsible, Kbd, Popover, Tooltip | | HextaAI | AI | 5 | Button, Dropdown menu, Sidebar, Toast, Tooltip | | Order Summary | E-commerce | 5 | Badge, Button, Input, Separator, Skeleton | | Product Search | E-commerce | 5 | Button, Kbd, Popover, Sheet, Spinner | | Markdown | AI | 4 | Alert, Button, Checkbox, Dropdown menu | | Stack Trace | AI | 4 | Button, Card, Collapsible, Tooltip | | Appearance | Settings | 3 | Button, Slider, Switch | | Save Bar | Settings | 3 | Button, Kbd, Spinner | | Voice Mode | AI | 3 | Button, Popover, Tooltip | | Price | E-commerce | 2 | Number flow, Skeleton | | Product Gallery | E-commerce | 2 | Button, Skeleton | | Streaming | AI | 2 | Bubble, Message | | Variant Picker | E-commerce | 2 | Button, Input | ## Methodology - Source: the 49 HextaUI Pro blocks in the block catalog on October 22, 2026. The catalog is generated from each block's source code at build time. - Included: 49 blocks. Excluded: none. - A block uses a component when one of its own source files imports it from components/ui. Demo files, usage examples and tests are not counted. A block whose other files import no component (an app assembled from other blocks, such as HextaAI) counts its entry file instead. A component reached only through another block counts for that other block. - The library is the 65 components in the HextaUI docs. Hooks and utilities are not counted. - These are blocks written by one author for HextaUI Pro, not a sample of apps on the web. Read them as how one production block library is built. - Every value is computed from code; none is entered by hand or by users. - Refreshed on every site build. The date on this page is the last change to the Pro block sources. - Percentages are rounded to the nearest whole number, so a table can add up to 99% or 101%. A median of an even count is the mean of the middle two values. - A finding about a group of blocks needs at least 20 blocks in each group. ## Frequently asked questions ### What is the most used UI component in HextaUI Pro blocks? Button. 46 of the 49 HextaUI Pro blocks (94%) import it, counted on October 22, 2026. Badge is second with 27 blocks. [Link](https://hextaui.com/research/ui-component-usage#faq-most-used-component) ### How many UI components does a typical HextaUI Pro block use? The median HextaUI Pro block imports 9 different UI components, counted across 49 blocks on October 22, 2026. The range is 2 to 23. [Link](https://hextaui.com/research/ui-component-usage#faq-components-per-block) ### Which HextaUI components are not used in any Pro block? Aspect ratio, Carousel, Data table, Item, Menubar, Navigation menu, Pagination, Scroll area and Video player. These 9 of the 65 HextaUI components are not imported directly by any of the 49 Pro blocks, counted on October 22, 2026. [Link](https://hextaui.com/research/ui-component-usage#faq-unused-components) ### How is a component counted as used by a block? A block uses a component when one of its own source files imports it from components/ui. Demo files, usage examples and tests are not counted, and a component reached only through another block counts for that other block. An app assembled from other blocks counts the components in its own entry file. [Link](https://hextaui.com/research/ui-component-usage#faq-how-usage-is-counted) ## Cite this research HextaUI. “UI Component Usage Statistics 2026: 49 Blocks Analyzed.” https://hextaui.com/research/ui-component-usage. Updated October 2026. ## Related - [All research](https://hextaui.com/research) - [HextaUI Pro blocks](https://hextaui.com/blocks) - [HextaUI components](https://hextaui.com/components) ---  # HextaUI and AI Elements > AI Elements gives you the pieces of an AI chat, such as a message, a prompt input and a tool call. HextaUI gives you the finished screens those pieces become, with the hard states already handled. This page compares them as of October 2026. Canonical: https://hextaui.com/compare/ai-elements Last updated: 2026-10-26 ## Two things called AI Elements [AI Elements](https://elements.ai-sdk.dev/) started at Vercel as a component library for the AI SDK. Its repository now says it will be deprecated at the end of November 2026 and replaced by [AI Elements from shadcn/ui](https://ui.shadcn.com/docs/ai-elements), a set of patterns you copy into your project with no package to install. This page covers both, because people searching for one usually find the other. ## The short answer Use AI Elements when you want free building blocks and plan to design the screens and their failure states yourself. Use HextaUI when you want the chat thread, the composer, the tool calls and the settings pages already built, with errors, retries, stops and approvals worked out. Both put their source in your project and share the shadcn/ui theme tokens, so you can mix them. ## At a glance | | HextaUI | AI Elements (shadcn/ui) | AI Elements (Vercel) | | --- | --- | --- | --- | | What you get | Components, AI blocks and a complete chat app | 21 patterns | 49 components | | Price | Components free, AI blocks paid once, [Prompt Input](https://hextaui.com/blocks/prompt-input) free | Free | Free | | License | MIT for components, Pro License for blocks | MIT | Apache 2.0 | | Primitives | Base UI | Base UI or Radix | Radix | | AI SDK | Optional, reads the same message parts | Used in the examples | Required by the setup guide | | Full screens | Chat app, artifacts, diff review, settings pages | No, you compose them | Example clones of popular chat apps | | Status | Active | New in October 2026 | Deprecated at the end of November 2026 | ## Pieces or screens A chat looks simple until something goes wrong. The reply fails halfway. The person stops it, edits an earlier message or sends another one while the model is still writing. A tool needs approval in the middle of a stream. An upload fails, or the model sends half a table. AI Elements gives you the parts to build each of those, and leaves the decisions to you. Its own Message example, for instance, shows Retry as an action you connect to `regenerate()` yourself. HextaUI blocks are those decisions, already made and tested: - [Chat Thread](https://hextaui.com/blocks/chat-thread): failed replies offer Try again, stopped replies say so, and edits and retries become versions you can switch between. Your question pins to the top while the answer streams, and older history loads without the view jumping. - [Prompt Input](https://hextaui.com/blocks/prompt-input): Enter never interrupts Japanese, Chinese or Korean input, uploads show progress and retry, messages typed during a reply wait in a queue, and drafts survive a reload. It is free. - [Tool Calls](https://hextaui.com/blocks/tool-calls): every AI SDK tool state has its own look, including approvals, with “Tell it what to do instead” to send a reason back to the model. - [Markdown](https://hextaui.com/blocks/markdown) and [Streaming](https://hextaui.com/blocks/streaming): replies never show half-typed syntax, and bursty chunks are revealed at a steady pace instead of stuttering. - [Artifact](https://hextaui.com/blocks/artifact): an edit that can’t be applied fails with a reason and keeps the last good version, previews swap in without a white flash, and runtime errors come with a Fix it action. - [Chat Sidebar](https://hextaui.com/blocks/chat-sidebar): delete with undo, rename in place, chats that are still replying, and thousands of chats that open instantly. [HextaAI](https://hextaui.com/blocks/hexta-ai) puts every block together into a complete chat app you can open and try before you install anything. ## Piece by piece Most AI Elements pieces have a HextaUI counterpart. The names below are from both AI Elements docs. | AI Elements | HextaUI | | --- | --- | | Conversation, Chat, Message | [Chat Thread](https://hextaui.com/blocks/chat-thread), with the free [Message](https://hextaui.com/docs/message) and [Message scroller](https://hextaui.com/docs/message-scroller) | | Prompt Input, Attachments, Model Selector, Context | [Prompt Input](https://hextaui.com/blocks/prompt-input), free | | Reasoning, Chain of Thought, Sources, Inline Citation | [Thinking](https://hextaui.com/blocks/thinking) | | Tool, Confirmation | [Tool Calls](https://hextaui.com/blocks/tool-calls) | | Plan, Queue, Task | [Agent Todos](https://hextaui.com/blocks/agent-todos) | | Code Block, Terminal, Snippet | [Code Block](https://hextaui.com/blocks/code-block) | | Artifact, Web Preview, JSX Preview | [Artifact](https://hextaui.com/blocks/artifact) | | File Tree, Commit | [Diff Review](https://hextaui.com/blocks/diff-review), with the free [Tree](https://hextaui.com/docs/tree) | | Checkpoint, message branches | Checkpoints and versions in [Chat Thread](https://hextaui.com/blocks/chat-thread) | | Persona, Speech Input, Voice Selector | [Voice Mode](https://hextaui.com/blocks/voice-mode) | | Shimmer | [Shimmer](https://hextaui.com/docs/shimmer), free | | Canvas, Node, Edge | No counterpart. HextaUI has no workflow canvas. | HextaUI also has screens AI Elements doesn’t cover, such as [Chat Sidebar](https://hextaui.com/blocks/chat-sidebar) and settings pages for an AI product like [Models](https://hextaui.com/blocks/models), [API keys](https://hextaui.com/blocks/api-keys) and [Billing](https://hextaui.com/blocks/billing). ## When AI Elements is the better choice - You want everything free and open source. Most of HextaUI’s AI blocks are paid. - You only need a few pieces and want to design the screens, and how they fail, yourself. - You need a workflow canvas with nodes and edges. Vercel’s version has one, and HextaUI doesn’t. - You want Radix primitives. HextaUI is built on Base UI only, while the shadcn/ui version offers both. - You want code maintained by shadcn/ui itself, with its community and examples behind it. ## Moving off Vercel’s AI Elements Nothing breaks at the end of November. The components are already source in your repository, and shadcn/ui says existing users don’t need to migrate. When you do touch those screens again, you have three options: keep the code and maintain it yourself, move to the shadcn/ui patterns, or replace a screen with a HextaUI block. HextaUI blocks read the same message parts that `useChat` returns, so your route handler and data stay as they are. Start with the composer, since [Prompt Input](https://hextaui.com/blocks/prompt-input) is free, then swap the thread and the tool calls when you need what they handle. ## Questions ### Is Vercel’s AI Elements being deprecated? Yes. The AI Elements repository says it will be deprecated at the end of November 2026 and replaced by AI Elements from shadcn/ui. Code you already copied into your project keeps working, because it lives in your repository. ### Does HextaUI need the AI SDK? No. The AI blocks read message parts in the same shape the AI SDK’s useChat returns, but they don’t import the SDK. Any backend works once its messages are mapped to those parts. ### Is HextaUI free? The components are free and MIT licensed. The AI blocks and full screens are HextaUI Pro, a single payment with every later block included. Prompt Input is free. ### Can I use HextaUI and AI Elements in the same project? Yes. Both put their source in your project and use the shadcn/ui theme tokens, so you can replace one screen at a time. ## More comparisons - [All comparisons](https://hextaui.com/compare) - [HextaUI vs assistant-ui](https://hextaui.com/compare/assistant-ui) - [HextaUI vs prompt-kit](https://hextaui.com/compare/prompt-kit) - [HextaUI vs shadcn/ui](https://hextaui.com/compare/shadcn-ui) - [shadcn AI chat templates](https://hextaui.com/compare/shadcn-ai-chat-templates) ---  # HextaUI and assistant-ui > assistant-ui is a chat framework: a runtime that manages the conversation, with components that read from it. HextaUI gives you finished screens as plain components, and leaves the state where it already is. This page compares them as of October 2026. Canonical: https://hextaui.com/compare/assistant-ui Last updated: 2026-10-26 ## The short answer Use assistant-ui when you want a free, complete chat framework and are happy to build on its runtime, especially with an agent backend such as LangGraph. Use HextaUI when you want finished screens in one design, from the chat to the settings pages of your AI product, as components you pass data to. Both put their source in your project and share the shadcn/ui theme tokens. ## At a glance | | HextaUI | assistant-ui | | --- | --- | --- | | What you get | Components, AI blocks and a complete chat app | A chat runtime, headless primitives and styled components | | Price | Components free, AI blocks paid once, [Prompt Input](https://hextaui.com/blocks/prompt-input) free | Free, with an optional paid cloud service | | License | MIT for components, Pro License for blocks | MIT | | Primitives | Base UI | Base UI or Radix | | Chat state | Yours. Blocks take messages as props | Held by an assistant-ui runtime | | Backends | Any, using AI SDK message parts | AI SDK, LangGraph, LangChain, AG-UI, A2A, Google ADK or your own | | Platforms | React on the web | React, plus React Native and terminal apps | | Product screens | Settings, models, API keys, billing and team pages | Focused on chat and agent interfaces | ## A framework or a set of screens [assistant-ui](https://github.com/assistant-ui/assistant-ui) starts from state. You wrap your app in `AssistantRuntimeProvider`, pick a runtime for your backend, and its components read the thread from that runtime. Branching, editing, attachments, tool approvals and resumable streams come from the runtime, and its styled components already show states like a stopped run or a failed reply. That is a lot of work done for you, and the trade is that your chat lives inside its model. Moving off it later means rewriting the state as well as the screens. HextaUI starts from the screen. Each block is a component you pass messages to, in the shape `useChat` returns, with the hard states already designed: - [Chat Thread](https://hextaui.com/blocks/chat-thread): failed replies offer Try again, stopped replies say so, and edits and retries become versions you can switch between. Your question pins to the top while the answer streams, and older history loads without the view jumping. - [Prompt Input](https://hextaui.com/blocks/prompt-input): Enter never interrupts Japanese, Chinese or Korean input, uploads show progress and retry, messages typed during a reply wait in a queue, and drafts survive a reload. It is free. - [Tool Calls](https://hextaui.com/blocks/tool-calls): every AI SDK tool state has its own look, including approvals, with “Tell it what to do instead” to send a reason back to the model. - [Settings](https://hextaui.com/blocks/settings): the pages around the chat, such as [Models](https://hextaui.com/blocks/models), [API keys](https://hextaui.com/blocks/api-keys), [Billing](https://hextaui.com/blocks/billing) and [Team](https://hextaui.com/blocks/team), in the same design. [HextaAI](https://hextaui.com/blocks/hexta-ai) puts every block together into a complete chat app you can open and try before you install anything. ## Piece by piece Most assistant-ui components have a HextaUI counterpart. The names below are from the assistant-ui docs. | assistant-ui | HextaUI | | --- | --- | | Thread, Message actions, Edit message, Error state | [Chat Thread](https://hextaui.com/blocks/chat-thread), with the free [Message](https://hextaui.com/docs/message) and [Message scroller](https://hextaui.com/docs/message-scroller) | | Message branches, Checkpoint history | Versions and checkpoints in [Chat Thread](https://hextaui.com/blocks/chat-thread) | | Composer, Composer attachments, Model selector, Message queue, Draft restore | [Prompt Input](https://hextaui.com/blocks/prompt-input), free | | Thread list, Thread list sidebar | [Chat Sidebar](https://hextaui.com/blocks/chat-sidebar) | | Reasoning, Sources, Inline citation | [Thinking](https://hextaui.com/blocks/thinking) | | Tool call, Tool group, Approval card | [Tool Calls](https://hextaui.com/blocks/tool-calls) | | Agent plan, Todo list | [Agent Todos](https://hextaui.com/blocks/agent-todos) | | Markdown text, Streaming text | [Markdown](https://hextaui.com/blocks/markdown) and [Streaming](https://hextaui.com/blocks/streaming) | | Syntax highlighter, Terminal block | [Code Block](https://hextaui.com/blocks/code-block) | | Artifact card, Web preview | [Artifact](https://hextaui.com/blocks/artifact) | | Reviewable diff, File tree | [Diff Review](https://hextaui.com/blocks/diff-review), with the free [Tree](https://hextaui.com/docs/tree) | | Composer voice, Voice conversation | [Voice Mode](https://hextaui.com/blocks/voice-mode) | | Runtimes, Assistant Cloud | No counterpart. HextaUI has no runtime or hosted storage, so the state stays in your code. | ## When assistant-ui is the better choice - You want everything free and open source. Most of HextaUI’s AI blocks are paid. - Your backend is an agent framework such as LangGraph, LangChain, AG-UI or Google ADK, and you want an adapter for it rather than mapping its messages yourself. - You want saved threads, run reports and analytics without building the storage. Assistant Cloud does that, and HextaUI has no hosted service. - You also ship a React Native or terminal app and want one chat model across them. HextaUI is web only. - You want Radix primitives. HextaUI is built on Base UI only. - You want the widest catalog of chat and agent components, with a large community behind it. ## Using them together Pick one to own the conversation. If assistant-ui already runs your chat, keep it, and use HextaUI for the screens around it, such as [Models](https://hextaui.com/blocks/models) or [API keys](https://hextaui.com/blocks/api-keys). If you are on the AI SDK and only want better screens, HextaUI blocks read the message parts `useChat` already gives you, so there is no runtime to adopt. Start with the composer, since [Prompt Input](https://hextaui.com/blocks/prompt-input) is free. ## Questions ### Is assistant-ui free? Yes. assistant-ui is open source under the MIT license. Assistant Cloud, its hosted service for saved threads and analytics, is optional and has a free plan alongside paid ones. ### Does HextaUI have a runtime like assistant-ui? No. HextaUI blocks are React components that take messages as props, in the same shape the AI SDK’s useChat returns. Your chat state stays in useChat, your own store or your server, and nothing wraps your app. ### Is HextaUI free? The components are free and MIT licensed. The AI blocks and full screens are HextaUI Pro, a single payment with every later block included. Prompt Input is free. ### Can I use HextaUI and assistant-ui in the same project? Yes, but let one of them own the chat. Both put their source in your project and use the shadcn/ui theme tokens, so HextaUI settings pages or components sit next to an assistant-ui thread without restyling. ## More comparisons - [All comparisons](https://hextaui.com/compare) - [HextaUI vs AI Elements](https://hextaui.com/compare/ai-elements) - [HextaUI vs prompt-kit](https://hextaui.com/compare/prompt-kit) - [HextaUI vs shadcn/ui](https://hextaui.com/compare/shadcn-ui) - [shadcn AI chat templates](https://hextaui.com/compare/shadcn-ai-chat-templates) ---  # HextaUI and prompt-kit > prompt-kit gives you the pieces of an AI chat, such as a message, a prompt input and a tool call, as free shadcn/ui components. HextaUI gives you the finished screens those pieces become, with the hard states already handled. This page compares them as of October 2026. Canonical: https://hextaui.com/compare/prompt-kit Last updated: 2026-10-26 ## The short answer Use prompt-kit when you want free, small pieces for a chat and plan to design the screens and their failure states yourself. Use HextaUI when you want the chat thread, the composer, the tool calls and the settings pages already built, with errors, retries, stops and approvals worked out. Both install with the shadcn CLI and share the shadcn/ui theme tokens, so you can mix them. ## At a glance | | HextaUI | prompt-kit | | --- | --- | --- | | What you get | Components, AI blocks and a complete chat app | Components and example blocks for AI chat | | Price | Components free, AI blocks paid once, [Prompt Input](https://hextaui.com/blocks/prompt-input) free | Free | | License | MIT for components, Pro License for blocks | MIT | | Primitives | Base UI | Radix, through shadcn/ui | | AI SDK | Optional, reads the same message parts | Optional, used in its chatbot examples | | Full screens | Chat app, artifacts, diff review, settings pages | Example layouts, including a chat app with a history sidebar | | Failure states | Stop, retry, failed replies, tool approvals and failed uploads handled | Left to you | ## Pieces or screens [prompt-kit](https://github.com/ibelick/prompt-kit) is a well-made set of pieces: a chat container that sticks to the bottom, a prompt input, Markdown, reasoning, sources and a tool call. What happens when something goes wrong is up to you. Its Tool component, for instance, shows a call as streaming, ready, done or failed, with no state for a call that waits for approval. Its Prompt Input sends on Enter without checking whether an input method is still composing, and its File Upload handles dropping files but not upload progress or a failed upload. HextaUI blocks are those decisions, already made and tested: - [Chat Thread](https://hextaui.com/blocks/chat-thread): failed replies offer Try again, stopped replies say so, and edits and retries become versions you can switch between. Your question pins to the top while the answer streams, and older history loads without the view jumping. - [Prompt Input](https://hextaui.com/blocks/prompt-input): Enter never interrupts Japanese, Chinese or Korean input, uploads show progress and retry, messages typed during a reply wait in a queue, and drafts survive a reload. It is free. - [Tool Calls](https://hextaui.com/blocks/tool-calls): every AI SDK tool state has its own look, including approvals, with “Tell it what to do instead” to send a reason back to the model. - [Markdown](https://hextaui.com/blocks/markdown) and [Streaming](https://hextaui.com/blocks/streaming): replies never show half-typed syntax, and bursty chunks are revealed at a steady pace instead of stuttering. - [Chat Sidebar](https://hextaui.com/blocks/chat-sidebar): delete with undo, rename in place, chats that are still replying, and thousands of chats that open instantly. [HextaAI](https://hextaui.com/blocks/hexta-ai) puts every block together into a complete chat app you can open and try before you install anything. ## Piece by piece Most prompt-kit components have a HextaUI counterpart. The names below are from the prompt-kit docs. | prompt-kit | HextaUI | | --- | --- | | Chat Container, Message, Scroll Button | [Chat Thread](https://hextaui.com/blocks/chat-thread), with the free [Message](https://hextaui.com/docs/message) and [Message scroller](https://hextaui.com/docs/message-scroller) | | Prompt Input, Prompt Suggestion, File Upload | [Prompt Input](https://hextaui.com/blocks/prompt-input), free | | Reasoning, Chain of Thought, Steps, Thinking Bar, Source | [Thinking](https://hextaui.com/blocks/thinking) | | Tool | [Tool Calls](https://hextaui.com/blocks/tool-calls) | | Markdown, Response Stream | [Markdown](https://hextaui.com/blocks/markdown) and [Streaming](https://hextaui.com/blocks/streaming) | | Code Block | [Code Block](https://hextaui.com/blocks/code-block) | | JSX Preview | [Artifact](https://hextaui.com/blocks/artifact) | | Text Shimmer, Loader | [Shimmer](https://hextaui.com/docs/shimmer) and [Spinner](https://hextaui.com/docs/spinner), free | | System Message | [Alert](https://hextaui.com/docs/alert), free | | Sidebar chat history, Full chat app | [Chat Sidebar](https://hextaui.com/blocks/chat-sidebar) and [HextaAI](https://hextaui.com/blocks/hexta-ai) | HextaUI also has screens prompt-kit doesn’t cover, such as [Diff Review](https://hextaui.com/blocks/diff-review), [Voice Mode](https://hextaui.com/blocks/voice-mode) and settings pages for an AI product like [Models](https://hextaui.com/blocks/models), [API keys](https://hextaui.com/blocks/api-keys) and [Billing](https://hextaui.com/blocks/billing). ## When prompt-kit is the better choice - You want everything free and open source. Most of HextaUI’s AI blocks are paid. - You need a small chat inside a larger app, where a message list, a prompt box and Markdown are enough. - You want to design the screens, and how they fail, yourself, and only need a good starting point for each piece. - You want Radix primitives. HextaUI is built on Base UI only. - You want a free, open-source chat app to start from. [Zola](https://github.com/ibelick/zola) is built with prompt-kit by the same author. ## Moving from prompt-kit You don’t have to replace everything at once. Both libraries copy source into your project, so swap one piece when you need what it handles. The composer is a good first step, since [Prompt Input](https://hextaui.com/blocks/prompt-input) is free and reads the same `useChat` status if your chat runs on the AI SDK. Replace the message list with [Chat Thread](https://hextaui.com/blocks/chat-thread) when failed replies, retries and edits start to matter. ## Questions ### Is prompt-kit free? Yes. prompt-kit is open source under the MIT license, and its components and example blocks install with the shadcn CLI. ### Does prompt-kit need the AI SDK? No. Its components don’t import the AI SDK, although its Tool component uses the same tool states and its chatbot examples are built on it. HextaUI works the same way: blocks read AI SDK message parts without importing the SDK. ### Is HextaUI free? The components are free and MIT licensed. The AI blocks and full screens are HextaUI Pro, a single payment with every later block included. Prompt Input is free. ### Can I use HextaUI and prompt-kit in the same project? Yes. Both put their source in your project and use the shadcn/ui theme tokens. prompt-kit builds on Radix and HextaUI on Base UI, so your project carries both while you mix them. ## More comparisons - [All comparisons](https://hextaui.com/compare) - [HextaUI vs AI Elements](https://hextaui.com/compare/ai-elements) - [HextaUI vs assistant-ui](https://hextaui.com/compare/assistant-ui) - [HextaUI vs shadcn/ui](https://hextaui.com/compare/shadcn-ui) - [shadcn AI chat templates](https://hextaui.com/compare/shadcn-ai-chat-templates) ---  # HextaUI and shadcn/ui > HextaUI is not a replacement for shadcn/ui. It is a registry you add to a shadcn/ui project, with the same CLI, the same component names and the same theme tokens. This page explains what it adds and when you don’t need it. Canonical: https://hextaui.com/compare/shadcn-ui Last updated: 2026-10-27 ## The short answer Use shadcn/ui when you want a clean starting point and plan to write the loading, error and empty states yourself. Add HextaUI when you want those states, the motion and the accessibility details already done, or when you need a component shadcn/ui doesn’t ship. You can mix both in one project, one component at a time. ## What stays the same - You install with the shadcn CLI, and the source is copied into your project. Nothing is locked inside a package. - Components keep the shadcn/ui names, parts and props, so `Dialog`, `DialogTrigger` and `DialogContent` work the way you expect. - Styling uses the same theme tokens, such as `--background`, `--primary` and `--radius`, with Tailwind CSS v4. - Files land in `@/components/ui`, next to any shadcn/ui components you already have. Adding a component looks like this: ```bash npx shadcn@latest add https://hextaui.com/r/button.json ``` ## What HextaUI adds - Finished states. Buttons show pending, success and error feedback from the promise you return. Switches save and roll back. Inputs shake when they are invalid. Spinners wait before they appear so fast work doesn’t flicker. - Motion you can interrupt. Animations share one set of easing curves and durations, can be reversed halfway and turn into a fade when reduced motion is on. - Touch, right-to-left and high contrast. Tap targets grow on touch screens, text inputs stay at 16px so iOS doesn’t zoom, layouts mirror for right-to-left languages and focus rings stay visible in Windows high contrast mode. - Components that aren’t in the shadcn/ui list at the time of writing (October 2026), such as [Tree](https://hextaui.com/docs/tree), [Video player](https://hextaui.com/docs/video-player), [Questionnaire](https://hextaui.com/docs/questionnaire), [Number flow](https://hextaui.com/docs/number-flow), [Shimmer](https://hextaui.com/docs/shimmer) and [Scroll fade](https://hextaui.com/docs/scroll-fade). - 9 hooks and 5 utilities you can install on their own, like [useButtonFeedback](https://hextaui.com/docs/use-button-feedback) and [useDelayedLoading](https://hextaui.com/docs/use-delayed-loading). - [49 blocks](https://hextaui.com/blocks) for AI products, such as a chat thread, tool calls and voice mode. These are part of HextaUI Pro, which is paid, and [Prompt Input](https://hextaui.com/blocks/prompt-input) is free. - Docs written for agents too. Every page has a Markdown version, and there is an [MCP server](https://hextaui.com/docs/mcp) your assistant can query. ## When shadcn/ui alone is the better choice - You want Radix primitives. HextaUI components are built on Base UI only. - You want the smallest possible component and would rather add states and motion yourself. HextaUI components carry more code because they handle more cases. - You depend on the shadcn/ui blocks, charts and themes, or on the community Vue and Svelte ports. HextaUI is React only. - You need the largest community and the most third-party examples. shadcn/ui has far more of both. ## Using both together Because the names and tokens match, you can replace one component at a time. Run the add command with `--overwrite` to swap a shadcn/ui component for the HextaUI version, then review the diff in git before you keep it. Components you don’t replace keep working. HextaUI has 65 components, and [Installation](https://hextaui.com/docs/installation) covers the theme tokens they expect. ## Component by component Each of these pages puts one HextaUI component next to its shadcn/ui version, with the parts, variants and props that differ. - [Accordion](https://hextaui.com/compare/shadcn-ui/accordion) - [Alert](https://hextaui.com/compare/shadcn-ui/alert) - [Alert dialog](https://hextaui.com/compare/shadcn-ui/alert-dialog) - [Avatar](https://hextaui.com/compare/shadcn-ui/avatar) - [Badge](https://hextaui.com/compare/shadcn-ui/badge) - [Bubble](https://hextaui.com/compare/shadcn-ui/bubble) - [Button](https://hextaui.com/compare/shadcn-ui/button) - [Card](https://hextaui.com/compare/shadcn-ui/card) - [Carousel](https://hextaui.com/compare/shadcn-ui/carousel) - [Chart](https://hextaui.com/compare/shadcn-ui/chart) - [Combobox](https://hextaui.com/compare/shadcn-ui/combobox) - [Command](https://hextaui.com/compare/shadcn-ui/command) - [Dialog](https://hextaui.com/compare/shadcn-ui/dialog) - [Dropdown menu](https://hextaui.com/compare/shadcn-ui/dropdown-menu) - [Empty](https://hextaui.com/compare/shadcn-ui/empty) - [Field](https://hextaui.com/compare/shadcn-ui/field) - [Hover card](https://hextaui.com/compare/shadcn-ui/hover-card) - [Input](https://hextaui.com/compare/shadcn-ui/input) - [Input group](https://hextaui.com/compare/shadcn-ui/input-group) - [Input OTP](https://hextaui.com/compare/shadcn-ui/input-otp) - [Item](https://hextaui.com/compare/shadcn-ui/item) - [Kbd](https://hextaui.com/compare/shadcn-ui/kbd) - [Message scroller](https://hextaui.com/compare/shadcn-ui/message-scroller) - [Pagination](https://hextaui.com/compare/shadcn-ui/pagination) - [Popover](https://hextaui.com/compare/shadcn-ui/popover) - [Progress](https://hextaui.com/compare/shadcn-ui/progress) - [Questionnaire](https://hextaui.com/compare/shadcn-ui/questionnaire) - [Radio group](https://hextaui.com/compare/shadcn-ui/radio-group) - [Scroll area](https://hextaui.com/compare/shadcn-ui/scroll-area) - [Sheet](https://hextaui.com/compare/shadcn-ui/sheet) - [Sidebar](https://hextaui.com/compare/shadcn-ui/sidebar) - [Skeleton](https://hextaui.com/compare/shadcn-ui/skeleton) - [Slider](https://hextaui.com/compare/shadcn-ui/slider) - [Spinner](https://hextaui.com/compare/shadcn-ui/spinner) - [Switch](https://hextaui.com/compare/shadcn-ui/switch) - [Table](https://hextaui.com/compare/shadcn-ui/table) - [Textarea](https://hextaui.com/compare/shadcn-ui/textarea) - [Tooltip](https://hextaui.com/compare/shadcn-ui/tooltip) For size, parts, variants and dependencies across every shadcn/ui component, see the [shadcn/ui component statistics](https://hextaui.com/research/shadcn-ui-components). ## More comparisons - [All comparisons](https://hextaui.com/compare) - [HextaUI vs AI Elements](https://hextaui.com/compare/ai-elements) - [HextaUI vs assistant-ui](https://hextaui.com/compare/assistant-ui) - [HextaUI vs prompt-kit](https://hextaui.com/compare/prompt-kit) - [shadcn AI chat templates](https://hextaui.com/compare/shadcn-ai-chat-templates) ---  # shadcn/ui AI chat templates > A shadcn/ui AI chat template is chat UI built from shadcn/ui components that you copy into your own project. Some give you pieces, some give you a whole app. This page compares seven options as of October 2026, and lists what a chat has to handle before you ship it. Canonical: https://hextaui.com/compare/shadcn-ai-chat-templates Last updated: 2026-10-22 ## What a chat template has to handle The message list and the composer take an afternoon. The states around them take weeks. Check a template against this list before you choose it: - Streaming that reads smoothly, without half-typed Markdown, broken tables or unclosed code fences on screen. - Stop, retry and a reply that fails halfway, each with its own message and next step. - Editing an earlier message or regenerating a reply, without losing the version that was there before. - Scrolling that follows new text until the reader scrolls up, and a way back down. - Tool calls that show what the model did, and approvals that can pause a reply until someone answers. - Attachments with upload progress, failures and retry, plus pasted text and dropped files. - A composer that doesn’t send halfway through Japanese, Chinese or Korean input, and keeps the draft if the page reloads. - An empty state, a chat history, and a layout that still works on a phone with the keyboard open. ## The options at a glance | | What you get | License | Backend | | --- | --- | --- | --- | | HextaUI | Finished chat screens and a complete chat app | MIT components, paid Pro blocks, free Prompt Input | Any, using AI SDK message parts | | Vercel Chatbot | A full Next.js app with sign-in and a database | Apache 2.0 | AI SDK | | AI Elements (shadcn/ui) | Patterns you compose | MIT | AI SDK in the examples | | AI Elements (Vercel) | Components, deprecated at the end of November 2026 | Apache 2.0 | AI SDK | | assistant-ui | Chat primitives with state management | MIT | AI SDK, LangGraph or your own | | prompt-kit | Components for AI apps | MIT | Any | | shadcn-chatbot-kit | Chat components | MIT | AI SDK | ## HextaUI HextaUI is a component library for shadcn/ui with Pro blocks for AI products. [HextaAI](https://hextaui.com/blocks/hexta-ai) is the complete chat app built from them: a chat sidebar, a thread with versions and checkpoints, thinking with sources, tool calls with approvals, artifacts beside the chat, streamed Markdown and voice mode. The blocks handle the states on the list above, and each one also works on its own. Choose it when you want the screens finished and would rather spend your time on the product. The composer, [Prompt Input](https://hextaui.com/blocks/prompt-input), is free. Install it without an account: ```bash npx shadcn@latest add https://hextaui.com/r/pro/prompt-input.json ``` ## Vercel Chatbot [Vercel Chatbot](https://github.com/vercel/chatbot), formerly called AI Chatbot, is a complete Next.js app with sign-in, a Postgres database, saved chats and the AI SDK. Choose it when you want a working product to deploy today and are happy with its design and its stack. ## AI Elements [AI Elements from shadcn/ui](https://ui.shadcn.com/docs/ai-elements) is a set of patterns, such as Chat, Message, Tool and Prompt Input, that you copy into your project. It replaces [Vercel’s AI Elements](https://elements.ai-sdk.dev/), which will be deprecated at the end of November 2026. Choose it when you want free, well-made pieces and plan to build the screens yourself. See [HextaUI vs AI Elements](https://hextaui.com/compare/ai-elements) for a piece-by-piece comparison. ## assistant-ui [assistant-ui](https://github.com/assistant-ui/assistant-ui) is a React library of chat primitives, such as a thread and a composer, with runtimes that manage chat state for the AI SDK, LangGraph or your own backend. Choose it when the hard part is state rather than the interface, for example an agent on LangGraph. ## prompt-kit and shadcn-chatbot-kit [prompt-kit](https://github.com/ibelick/prompt-kit) and [shadcn-chatbot-kit](https://github.com/Blazity/shadcn-chatbot-kit) are free component kits that install with the shadcn CLI. They are a good fit for a small chat inside a larger app, where you need a message list, a prompt box and Markdown, and little else. ## How to choose - You want a deployable app this week and its stack suits you: Vercel Chatbot. - You want free pieces and full control of the design: AI Elements from shadcn/ui, or prompt-kit. - Your backend has complex chat state, such as LangGraph: assistant-ui. - You want finished screens with the hard states handled, plus settings pages for your AI product: HextaUI. They mix well. Most of them copy shadcn/ui source into your project and share the same theme tokens, so you can keep one and replace a single piece with another. For example, keep the Vercel Chatbot backend and swap its composer for Prompt Input, which reads the same `useChat` status. ## More comparisons - [All comparisons](https://hextaui.com/compare) - [HextaUI vs AI Elements](https://hextaui.com/compare/ai-elements) - [HextaUI vs assistant-ui](https://hextaui.com/compare/assistant-ui) - [HextaUI vs prompt-kit](https://hextaui.com/compare/prompt-kit) - [HextaUI vs shadcn/ui](https://hextaui.com/compare/shadcn-ui) ---  # Privacy Policy > What data HextaUI collects, why, who processes it and the choices you have. Canonical: https://hextaui.com/legal/privacy Last updated: 2026-10-26 HextaUI (hextaui.com) is run by Preet Suthar, an individual based in India. This policy explains what data the site collects, why, who else handles it and what you can ask for. Questions go to [hi@preetsuthar.me](mailto:hi@preetsuthar.me). ## The short version - You can read the docs and use every free component without an account. Google Analytics cookies are only set if you allow them. - If you sign in, I keep your name, email and profile picture from GitHub or Google so your account and HextaUI Pro work. - Payments go through Dodo Payments. I never see your full card details. - Signed-in accounts get a short email when new components or blocks ship. One click in any email, or a switch in your account, turns them off. - I don’t sell your data, show ads or track you across sites. ## When you browse Reading the site needs no account. These things happen on every visit, and Google Analytics only if you agree to it: - Analytics. OneDollarStats records aggregate statistics: the page you came from, the pages you view, how long you stay, and your device type, operating system, browser and country. It doesn’t collect personally identifiable data from browsing and sets no cookies. - First-party analytics. Minilytics, a small analytics tool I run myself on Cloudflare, records the pages you view, the page you came from, how long the page stays open, your screen width, and which buttons you click on this site. It sets two cookies to tell visits apart. If you buy something, those two IDs are attached to the payment so I can see which page or post led to it. If you sign in, your visits are linked to your account’s ID, name and email. Visit any page with `?ml_ignore=true` to opt out in that browser. - Bots and AI agents. When a crawler, AI assistant, coding agent or other automated tool requests a page, or anyone requests a file meant for them (Markdown pages, `llms.txt`, `robots.txt` or the component registry), the server sends a record of that request to Minilytics: the URL, the response status, the user agent, the `Accept` and `Signature-Agent` headers, the referring page, the IP address and the country. It’s used to see which assistants read and cite which pages. Ordinary page views in a browser aren’t recorded this way, and no cookies are involved. - Google Analytics, if you allow it. The first time you visit, a banner asks whether HextaUI can use Google Analytics. Only if you choose Allow does it load and set cookies to count visits and see which pages are used: the pages you view, how you got there, roughly where you are, and your device and browser. If you choose Decline, it never loads. - Hosting. Cloudflare serves the site and, like any web host, processes your IP address and browser details to deliver pages and block abuse. ## When you sign in You sign in with GitHub or Google. With your permission on their screen, they share the following, which I store: - Your name, email address and profile picture URL. - Your account ID with that provider and whether your email is verified. - The access tokens the provider issues. They’re encrypted in the database and only used to complete sign-in. - For each session: a session token, the IP address and browser you signed in from, and when the session expires. If you sign in with both GitHub and Google using the same verified email, both connect to one account, so your purchase follows you. ## When you buy HextaUI Pro Dodo Payments is the merchant of record. It collects your payment details, billing address and tax information, processes the payment and issues the invoice, under its own privacy policy. From Dodo I receive and keep the payment ID, its customer ID for you, the product, amount, currency, status and date. You can pay before you have an account. Until you sign in, I also keep the name and email you gave at checkout, so I can email you a link to unlock Pro and match the purchase when you sign in with that email. Once the purchase is on your account, that copy is deleted. ## When you sponsor HextaUI If you book the sponsor slot, I store the card copy you write, the link and the contact email you give, plus the subscription ID, customer ID and status that Dodo Payments sends back. The copy is published on the site; the email is only used for the sponsorship. Dodo Payments handles the payment as merchant of record. ## When you manage a Team plan If you buy Team and add teammates, I store the email addresses you add and when you added them, so those people get Pro when they sign in. Each teammate gets one email saying who added them and how to sign in. Only add people who expect it. Removing a teammate deletes their email from the team. ## When you create API tokens Tokens let the shadcn CLI install Pro blocks. I store only a hash of each token, the name you give it, a short hint like `hxt_abcd…wxyz`, and when it was created and last used. The full token is shown to you once and can’t be recovered. ## Emails Some emails come with your account: a welcome email when you sign up, a confirmation when you buy HextaUI Pro, and the email a teammate gets when you add them to a Team plan. These are sent once each and aren’t marketing. When new components or blocks ship, I email the address on your account to say what’s new. Every account starts subscribed. Each email has an unsubscribe link that works in one click, and you can turn release emails on or off any time in [your account](https://hextaui.com/account). I keep a record of which release emails went to which account so nobody gets the same one twice, and the date you unsubscribed so I stop emailing you. You can also get release emails without an account, by entering your email address in the form at the bottom of any page. I store that address, the page you subscribed from, the last release email sent to it, and the date you unsubscribed if you do. It’s used only for release emails. ## How the data is used - To sign you in and keep you signed in. - To check your HextaUI Pro access and deliver Pro blocks. - To process purchases, refunds and disputes. - To prevent fraud and abuse, such as shared or leaked tokens. - To email you when new components and blocks ship. - To answer you when you email me. - To understand, in aggregate, which pages are useful. - To see which AI assistants and agents read the docs and which pages they cite. - To see which pages, posts and links lead to sign-ups and purchases. ## Cookies and browser storage Without your consent, the only cookies are the two first-party analytics cookies and the ones that make sign-in work. Minilytics sets `ml_vid`, a random visitor ID that lasts a year, and `ml_sid`, a random session ID that expires after 30 minutes without activity. The authentication system sets these (their names start with `better-auth`): - A session cookie that keeps you signed in for up to 30 days. - A short-lived copy of your session, refreshed every few minutes. - A sign-in state cookie that lasts a few minutes while GitHub or Google redirects you back. If you allow analytics, Google Analytics also sets cookies whose names start with `_ga`, which last up to two years. You can change your choice any time with Cookie settings in the footer. Choosing Decline there removes these cookies and stops Google Analytics. The site also saves a few preferences in your browser’s storage: your analytics choice, your theme, your package manager, recent searches, the layout of resizable examples, whether you’ve signed in before, and a cached GitHub star count. These never leave your device. ## Who else handles data - Cloudflare hosts the site, its functions and the database, and delivers release emails. - GitHub and Google handle sign-in under their own privacy policies. - Dodo Payments processes payments, taxes and refunds. - OneDollarStats provides analytics, hosted in Finland. - Minilytics is my own analytics service. It runs on my Cloudflare account, receives records of requests from bots and AI agents, and receives payment details from Dodo Payments so purchases can be matched to visits. - Google provides Google Analytics, only if you allow it, under its own privacy policy. Some pages also load content straight from other services, which then receive your IP address and browser details: the GitHub API for the star count, profile pictures from GitHub and Google, sample images and videos in docs examples (Unsplash, W3C and MDN), and site icons in the Thinking block preview through DuckDuckGo’s icon service. These providers may process data outside India. ## How long data is kept - Account data: until you ask me to delete your account. - Sessions: they expire after 30 days without use, or when you sign out. - API tokens: until you revoke them or delete your account. - Release email records: until you delete your account. - Email addresses subscribed without an account: until you ask me to delete them. Unsubscribing stops the emails straight away. - Teammate emails: until the Team owner removes them, or the Team plan is refunded or deleted. - Purchase records: kept for as long as tax, accounting and fraud rules require, even after the account is deleted. ## Your rights Under India’s Digital Personal Data Protection Act, 2023, and, where it applies to you, the GDPR, you can ask to access, correct or delete your data, withdraw consent, or raise a grievance. Email [hi@preetsuthar.me](mailto:hi@preetsuthar.me) from the address on your account and I’ll respond within 30 days. Deleting your account removes your profile, linked sign-ins, sessions and API tokens, and ends Pro access. ## Children HextaUI accounts and purchases are meant for people 18 or older. If you’re younger, ask a parent or guardian before signing in or buying. ## Security Traffic is encrypted with HTTPS, API tokens are stored only as hashes and provider tokens are encrypted. No system is perfectly secure, so please keep your tokens private and revoke any you think have leaked. ## Changes If this policy changes, the date at the top changes too. Material changes will be announced on the site. See also the [Terms of Service](https://hextaui.com/legal/terms). ---  # Terms of Service > The terms for using HextaUI: the free components, your account, HextaUI Pro purchases, acceptable use and ownership. Canonical: https://hextaui.com/legal/terms Last updated: 2026-10-27 These terms cover your use of HextaUI (hextaui.com), run by Preet Suthar, an individual based in India. By using the site, signing in or buying HextaUI Pro, you agree to them. Questions go to [hi@preetsuthar.me](mailto:hi@preetsuthar.me). ## What HextaUI offers - Free components. The components, hooks and docs in the [open-source repository](https://github.com/preetsuthar17/hextaui) are released under the MIT License. Nothing in these terms limits your rights under that license. - HextaUI Pro.** A one-time purchase that unlocks the code for Pro blocks, on the site and through the shadcn CLI. Your use of Pro code is covered by the [Pro License](https://hextaui.com/legal/license). ## Your account - You sign in with GitHub or Google and need to be 18 or older, or have a guardian’s consent. - An account belongs to one person. Don’t share it. - Keep your API tokens private. You’re responsible for what happens with them, and you can revoke them at any time from your account page. ## Purchases - HextaUI Pro costs the price shown at checkout, charged once. Taxes may be added depending on where you live. - Dodo Payments is the merchant of record. It processes the payment, handles taxes and sends the invoice, and its terms apply to the payment itself. - Access is for the lifetime of HextaUI Pro and includes blocks added later. If Pro is ever discontinued, you can keep using the code you already have under the Pro License. - Refunds are covered by the [Refund Policy](https://hextaui.com/legal/refunds). ## Acceptable use Please don’t: - Share your account or API tokens, or resell access. A Team plan may keep one shared token in CI, as the Pro License describes. - Redistribute Pro code outside what the Pro License allows. - Get around access controls, scrape gated content, or use the site in a way that overloads or harms it. - Use HextaUI for anything illegal. Breaking these rules, filing a fraudulent chargeback, or abusing the service can lead to your tokens being revoked and your account and Pro access being suspended or closed. ## Ownership The HextaUI name, site and Pro blocks belong to Preet Suthar. Free components are open source under the MIT License. Pro blocks are licensed to you, not sold. ## Disclaimers HextaUI is provided “as is” and “as available”. Components and blocks are carefully built and tested, but there’s no guarantee they are free of bugs or fit your project. Test them in your product before you ship. The site may change, pause or be unavailable at times. ## Limitation of liability To the extent the law allows, I’m not liable for indirect, incidental or consequential damages, such as lost profits or data, arising from your use of HextaUI. My total liability for any claim is limited to the amount you paid for HextaUI Pro in the 12 months before the claim. Nothing here limits rights you have that can’t be waived by law. ## Ending your use You can stop using HextaUI at any time and ask me to delete your account. I may suspend or close accounts that break these terms. The sections on ownership, disclaimers and liability continue to apply after that. ## Changes I may update these terms as HextaUI changes. The date at the top shows the latest version, and material changes will be announced on the site. Continuing to use HextaUI after a change means you accept it. ## Governing law These terms are governed by the laws of India, and disputes are subject to the jurisdiction of the courts of India. Before any formal dispute, please email [hi@preetsuthar.me](mailto:hi@preetsuthar.me) so we can try to sort it out. ---  # Refund Policy > HextaUI Pro, Solo or Team, comes with a 30-day, no-questions-asked refund. Canonical: https://hextaui.com/legal/refunds Last updated: 2026-10-27 If HextaUI Pro isn’t right for you, Solo or Team, you can get a full refund within 30 days of your purchase. No questions asked. ## How to ask for a refund Email [hi@preetsuthar.me](mailto:hi@preetsuthar.me) within 30 days of buying. Send it from, or mention, the email you used at checkout, and include the order or payment ID from your receipt if you have it. Refunds are issued through Dodo Payments to your original payment method. Once approved, they usually arrive within 5 to 10 business days, depending on your bank. ## What happens after a refund - Your HextaUI Pro access ends. - On a Team plan, every teammate’s access ends too. - Your API tokens stop working for Pro blocks. - Your [Pro License](https://hextaui.com/legal/license) ends, so please remove Pro code from your projects. ## After 30 days Purchases are final after 30 days, except for duplicate charges, billing errors, or where the law gives you a right to a refund. ## Chargebacks Please email me before disputing a charge with your bank. It’s faster for you. A chargeback ends Pro access while the dispute is open, and for good if the dispute is lost. ## Your consumer rights This policy doesn’t limit any rights you have under the consumer law where you live. See also the [Terms of Service](https://hextaui.com/legal/terms). ---  # Pro License > What you can build with HextaUI Pro blocks, and what you can’t do with the code. Canonical: https://hextaui.com/legal/license Last updated: 2026-10-27 This license covers the code of HextaUI Pro blocks. It applies when you buy HextaUI Pro, and lasts as long as you follow it. The free components in the [open-source repository](https://github.com/preetsuthar17/hextaui) stay under the MIT License and aren’t affected. ## What you get A perpetual, worldwide, non-exclusive, non-transferable license for the people your plan covers to use, copy and modify Pro blocks in their own end products. Solo covers you, the buyer. Team covers the buyer and up to nine teammates they give a seat on their account page. Free blocks, like Prompt Input, are covered the same way for anyone who installs them. An end product is an app, website or piece of software where the blocks are part of something larger, not a collection of the blocks themselves. ## You can - Use Pro blocks in unlimited personal and commercial projects. - Use them in work for clients, and hand the finished project to them. - Use them in products you sell, including SaaS apps and paid apps. - Modify the code however you like. - Include them in an open-source end product, as long as the project isn’t a UI library, kit or template collection. ## You can’t - Resell, redistribute or sublicense Pro code on its own, as templates, or as part of a UI kit, component library, design system, theme or page builder. - Publish Pro code in a way that lets others use it without buying, such as a public registry, gist or snippet collection. - Share your account or API tokens with anyone, except the one shared CI token a Team plan allows. - Use Pro code to build a product that competes with HextaUI Pro, or to train AI models that generate UI components for others. ## Teams Each developer who installs or works on Pro code needs a seat: their own Solo plan, or a seat on a Team plan. A Team plan has 10 seats, including the buyer’s. An Unlimited plan bought before 27 October 2026 keeps no seat limit and covers the developers of one company. The buyer can move a seat from one teammate to another at any time, and the team may keep one shared API token in continuous integration and build systems. Clients and colleagues who only use the finished product don’t need a seat. ## Ownership and ending the license Pro blocks are licensed to you, not sold, and remain the property of Preet Suthar. The license ends if you get a refund, lose a chargeback, or break these terms. When it ends, stop using Pro code in new work and remove it from your projects. ## No warranty Pro blocks are provided “as is”, as described in the [Terms of Service](https://hextaui.com/legal/terms). ## Questions Not sure whether your use is covered? Email [hi@preetsuthar.me](mailto:hi@preetsuthar.me) and ask before you ship.