with no role, so an alert that is there at load is read in order, like the rest of the page. - role="alert" makes screen readers read the message at once, even mid-sentence. Use it only for urgent messages added after load. - role="status" waits until the screen reader is quiet. Keep that alert on the page and change its text. Some screen readers miss a status region that arrives together with its text. - AlertIcon is aria-hidden, and color is not read out. The title must say what kind of message it is, like "Payment failed". - AlertTitle is a \

, not a heading. Put an \

or \

inside it if the alert needs to be in the page outline. - The theme tests hold alert text to 4.5:1: solid and soft text on their own fills, and outline and ghost text on the page background. ### Examples #### Information that is on the page at load ```tsx import { Info } from "lucide-react"; Planned maintenance The dashboard is read-only on Sunday from 02:00 to 04:00 UTC. ``` #### An error after a failed save ```tsx import { CircleAlert } from "lucide-react"; function SaveError({ error }: { error: string | null }) { if (!error) return null; return ( Your changes were not saved {error} ); } ``` #### A status that changes while it stays on the page ```tsx function SaveStatus({ saving }: { saving: boolean }) { return ( {saving ? "Saving…" : "All changes saved"} ); } ``` #### With actions (needs @txbrendan/button) ```tsx import { Button } from "@/components/ui/button"; Your trial ends in 3 days Add a payment method to keep your projects. Compare plans ``` ## Approval Request > An AI agent asks before it acts: what it wants to do, why, and the command or change. Approve or Reject, then the outcome shows in place of the buttons and cannot be pressed again. - Name: `approval-request` - Status: beta - Categories: ai, forms - File: the install writes `approval-request.tsx` to your `ui` alias, `@/components/ui` by default. - Other registry items: `@txbrendan/button`, `@txbrendan/card`, `@txbrendan/checkbox`, `@txbrendan/motion-timing`, `@txbrendan/notice`, `@txbrendan/tooltip`. The install adds them. - Gallery: https://txbrendan.dev/components/approval-request - Registry item: https://txbrendan.dev/r/approval-request.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/approval-request ``` ### Use it for - An agent is about to do something hard to undo, like run a migration, send email, spend money, or deploy, and a person should say yes first. - Put the action in title, like "Run migration 0042 on production?", and why in reason. - Pass command for a shell command, or diff for a change to a file. Pass detail for anything else to look at first. - Set tone to the risk. danger colors the tile and the Approve button red. - Pass allowAlways for an action the person may trust from now on. onApprove gets { always }. - Left alone, it holds its own outcome. To send the answer first, pass outcome, set loading while it sends, then set outcome to "approved" or "rejected". - If the answer fails to send, keep outcome null and pass error. - ⌘ or Ctrl + Enter approves and Esc rejects, only while focus is in the card, so two cards on a page never both answer. The buttons' tooltips teach the keys. Pass keys={false} to turn them off. - Pass keys="page" when the page shows one request at a time, like a single chat. Then the keys work anywhere on the page. They do nothing while someone types in a field or a modal dialog is open. - With keys="page", Esc rejects only when no menu, popup, or dialog is open, since Esc closes those first. If two pending cards use it, only the one shown last answers, unless focus is in another request. - The tooltips load the first time someone points at or tabs into a card, so a page that never uses the keys never loads them. Call loadApprovalTooltip() early, like when an agent run starts, to have them ready. - Pass expiresIn, in seconds, for a request that should not wait forever. It pauses while the pointer or focus is on the card. When it runs out, the outcome is "expired" and onExpire is called. ### Avoid it for - An action the person started themselves, like deleting a file. Use Alert Dialog. - An action that is easy to undo. Do it, and offer Undo in a toast. - Plain consent to terms, by name. Use Agreement. ### Props - `title`: `ReactNode`. Required. What the agent wants to do. It names the request. - `reason`: `ReactNode`. Why it wants to, in plain words. - `command`: `string`. A shell command it will run. Shows in a code block that scrolls sideways. - `diff`: `string`. A unified diff. Added lines show green and removed lines red. The + and - stay in the text. - `detail`: `ReactNode`. Anything else to look at first, like a list of recipients. - `icon`: `ReactNode`. Replaces the shield in the tile. Pass null for no tile. - `tone`: `"neutral" | "brand" | "danger" | "success" | "warning"`. Default `"neutral"`. How risky the action is. Colors the tile and the Approve button. - `outcome`: `"approved" | "rejected" | "expired" | null`. The outcome, when you hold it. null while it waits. - `defaultOutcome`: `"approved" | "rejected" | "expired" | null`. Default `null`. The outcome it starts with, when it holds its own. - `onApprove`: `(answer: { always: boolean }) => void`. Called on Approve or ⌘ Enter. always is true when Always allow was ticked. - `onReject`: `() => void`. Called on Reject or Esc. - `expiresIn`: `number`. Seconds to answer. Shows "Expires in 0:42" by the buttons, in warning for the last 10. Pauses while the pointer or focus is on the card. - `onExpire`: `() => void`. Called when the countdown runs out. Holding the outcome yourself, set it to "expired" here. - `keys`: `boolean | "page"`. Default `true`. ⌘ or Ctrl + Enter approves and Esc rejects, while focus is in the card. "page" makes them work anywhere on the page. - `allowAlways`: `boolean`. Default `false`. Shows an Always allow checkbox before the buttons. - `defaultAlways`: `boolean`. Default `false`. Ticks Always allow at the start. - `alwaysLabel`: `ReactNode`. Default `"Always allow this action"`. The checkbox's words. - `approveLabel`: `ReactNode`. Default `"Approve"`. The Approve button's words. - `rejectLabel`: `ReactNode`. Default `"Reject"`. The Reject button's words. - `outcomeNote`: `ReactNode`. A short line after the outcome, like "Ran in 4 s". - `error`: `ReactNode`. In red under the buttons, like an answer that failed to send. Announced once. - `loading`: `boolean`. Default `false`. The pressed button shows a spinner, and nothing else can be pressed. - `disabled`: `boolean`. Default `false`. Blocks both buttons and the checkbox. - `size`: `"sm" | "md"`. Default `"md"`. Text, tile, and button size. sm fits a chat thread. - `className`: `string`. Classes for the card. Later classes win. ### Accessibility - The card is a group named by the title, so each Approve is heard with what it approves. - Once decided, the buttons are gone and focus moves to the outcome, so screen readers read Approved, Rejected, or Expired. - The buttons carry aria-keyshortcuts from the start, and their tooltips show the keys. The keys work only while focus is in the card, or anywhere with keys="page". - The tooltips load on the first hover or focus. Focus stays on the button it was on while they load in. - Keys never act while someone types in a field. With keys="page", they wait while a modal dialog is open, and Esc waits while any menu, popup, or dialog is open. - The countdown is a timer, which screen readers do not read out each second. It pauses while focus is in the card, so no one runs out of time while they read. - The command and the diff are focusable, named groups, so a long line scrolls from the keyboard. - Diff lines keep their + and -, so the change does not rest on color alone. - While loading, the pressed button keeps focus and says it is busy. An error is described on both buttons and announced once. - The tile's icon is hidden from screen readers. In forced-colors mode the tile draws a border. ### Examples #### A risky command ```tsx ``` #### Send the answer, then show it ```tsx "use client"; import { useState } from "react"; import { ApprovalRequest, type ApprovalOutcome } from "@/components/ui/approval-request"; export function DeployRequest({ send }: { send: (approved: boolean) => Promise }) { const [outcome, setOutcome] = useState(null); const [loading, setLoading] = useState(false); const [error, setError] = useState(); async function answer(approved: boolean) { setLoading(true); setError(undefined); try { await send(approved); setOutcome(approved ? "approved" : "rejected"); } catch { setError("The answer did not send. Try again."); } finally { setLoading(false); } } return ( answer(true)} onReject={() => answer(false)} /> ); } ``` #### Load the tooltips when a run starts ```tsx "use client"; import { ApprovalRequest, loadApprovalTooltip } from "@/components/ui/approval-request"; import { Button } from "@/components/ui/button"; export function AgentRun({ start, request }: { start: () => void; request?: { title: string; command: string } }) { return ( <> {request && } ); } ``` ## Area Chart > Filled areas that show how amounts change over time, alone or stacked into a total, with a themed tooltip, legend, and states. - Name: `area-chart` - Status: beta - Categories: charts - File: the install writes `area-chart.tsx` to your `ui` alias, `@/components/ui` by default. - npm packages: `recharts`, `react-is`. The install adds them. - Other registry items: `@txbrendan/chart`, `@txbrendan/chart-key`, `@txbrendan/dither`, `@txbrendan/dither-motion`, `@txbrendan/motion-timing`. The install adds them. - Gallery: https://txbrendan.dev/components/area-chart - Registry item: https://txbrendan.dev/r/area-chart.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/area-chart ``` ### Use it for - Showing how an amount changes over time, when the size of the amount matters, like storage used. - Use stacked to show how parts add up to a total over time, like visitors by device. - Pass data, a config with one entry per area, and the categoryKey for the x axis. - Pass valueFormat to format the tooltip and the y axis. - Pass legend="top" for a key beside the title in place of the tooltip box. It shows the point under the pointer, and its numbers roll as you move. Press a series in the key to hide or show it. - Dithered, the dots melt away toward the bottom and fade in from the axis, and hidden dots fill in near the pointer. Pass fill, start, line, intro, hover, or idle to change how they sit and move, or set them on a Dither around the chart. ### Avoid it for - Comparing trends that cross each other without stacking. Overlapping fills hide each other. Use LineChart. - Categories with no order, like regions. Use BarChart. - A small trend next to a number or in a table cell. Use Sparkline. - More than five areas. The theme has five chart colors. ### Props - `data`: `TData[]`. One object per point on the x axis, like { month: "Jan", desktop: 186 }. - `config`: `{ [key in keyof TData]?: { label: string; color?: string } }`. The areas to draw, in order. Colors default to --chart-1 through --chart-5. - `categoryKey`: `keyof TData`. The field that names each point, shown on the x axis. - `title`: `ReactNode`. A visible title. It names the chart. TypeScript requires title, aria-label, or aria-labelledby. - `aria-label`: `string`. Names the chart when it has no visible title. - `size`: `"sm" | "md" | "lg"`. Default `"md"`. Height: 5, 7, or 9 times --control-h-md, so density scales it. - `stacked`: `boolean`. Default `false`. Stacks the areas, so the top edge shows the total. - `curve`: `"linear" | "monotone" | "step"`. Default `"monotone"`. How the top edge joins its points. Monotone is smooth and never overshoots a point. - `valueFormat`: `Intl.NumberFormatOptions`. Formats tooltip values, and y axis ticks in short form, like 12.5K. - `locale`: `string`. Default `"en-US"`. The locale for numbers. Fixed, so server and browser print the same text. - `legend`: `boolean | "top"`. Shows the legend. By default it shows when there are two or more areas. "top" shows it as a key beside the title, with the point under the pointer in place of the tooltip box, and the last point at rest. - `loading`: `boolean`. Default `false`. Shows a soft area shape at the same height. When data arrives, it fades out while the areas draw in. - `error`: `ReactNode`. Shows this message in place of the chart. true shows a default message. - `onRetry`: `() => void`. Shows a retry button under the error. - `emptyText`: `ReactNode`. Default `"No data yet"`. Shown when data is empty. - `texture`: `"flat" | "dither" | "gradient" | "grain"`. dither draws each area as dots that thin out toward the bottom and fade in from the axis, gradient fades it down from the top, and grain speckles it. The edge stays solid. Hover fills it in. Left out, the chart follows the Texture around it. - `fill`: `"scatter" | "steps"`. Default `"scatter"`. Dithered, how the dots thin toward the bottom: one by one, or in 8 even steps. Left out, the chart follows the Dither around it. - `start`: `"fade" | "gap"`. Default `"fade"`. Dithered, how the areas start: fading in from the axis over 48 px, or 16 px in from it, then fading. Left out, the chart follows the Dither around it. - `line`: `"fade" | "dots"`. Default `"fade"`. Dithered, how each line starts: fading in over the same 48 px as the dots, or breaking into dots there. Left out, the chart follows the Dither around it. - `intro`: `"fade" | "sweep" | "rain" | "ripple" | "pop" | "fall"`. Default `"fade"`. Dithered, how the dots come in when the chart first shows. Motion off plays none. Left out, the chart follows the Dither around it. - `hover`: `"fill" | "none"`. Default `"fill"`. Dithered, "fill" fills in hidden dots near the pointer, and they fade back when it leaves. Left out, the chart follows the Dither around it. - `idle`: `"none" | "wave" | "twinkle" | "breathe" | "drift"`. Default `"none"`. Dithered, what the dots do at rest: a band of extra dots passing across, single dots blinking out and on, the thin edge filling in deeper and back, or soft patches of extra dots drifting across. Left out, the chart follows the Dither around it. - `className`: `string`. Extra classes. Later classes win, so className='h-96' replaces the height. ### Accessibility - Renders a \
named by its title, or by aria-label. TypeScript requires one. - Recharts' keyboard layer stays on: Tab focuses the chart, the arrow keys move between points, and the tooltip reads each one out. With the key on top, the key follows the arrow keys too, and the tooltip stays on the page for screen readers only, so each point is still read out. - The key on top sits beside the title, not in it, so the chart's name never changes as the key moves. Each value holds the width of its longest one, so the key stays still as its numbers roll. - Each series in the key is a toggle button. A hidden area fades out where it is, leaves the tooltip, and keeps the y axis still. In a stack, the rest glide down to close the gap once it has faded. The last one shown cannot hide. Tab reaches these buttons first, then the chart. - Keeps one height while it loads, draws, fails, or has no data, so the page does not move. When the page prints, it asks the browser to keep a chart that fits on one page whole. In the light theme, it asks the browser to print legend dots and loading shapes even with backgrounds off. - Loading, the error, and the empty text are read out through a status line that stays on the page. - Each area's edge is a 2px line in --chart-1 to --chart-5, which the theme tests hold to 3:1 against the page. The fill under it fades out, so the edge carries the color. - Areas draw in over three times --motion-duration-base, once the chart is on screen. They finish at once when the page prints. At 0ms they draw at once, and Recharts skips the animation for reduced motion. - Dithered dots move only while the theme's pulse runs, so reduced motion and motion off keep them still. Forced colors keeps them still too, and shows every grid line. A print shows the still dots. ### Examples #### One area, with units ```tsx ``` #### Stacked ```tsx ``` #### Key beside the title in place of the tooltip ```tsx ``` #### While it loads, and when it fails ```tsx refetch()} /> ``` ## Audience > Who a message goes to, said before it is sent, with messages for juniors, people under 18, going to their parents or guardians. - Name: `audience` - Status: beta - Categories: people, display - File: the install writes `audience.tsx` to your `ui` alias, `@/components/ui` by default. - Other registry items: `@txbrendan/avatar`, `@txbrendan/avatar-stack`, `@txbrendan/button`, `@txbrendan/hover-card`, `@txbrendan/peek-card`. The install adds them. - Gallery: https://txbrendan.dev/components/audience - Registry item: https://txbrendan.dev/r/audience.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/audience ``` ### Use it for - Above a message, before it is sent, so the sender knows who will read it. - Pass everyone the message is for in to. Mark juniors and give their guardians. - Set juniorMessages from your app's setting. "guardians" sends juniors' messages to their parents instead. "copy" sends them to the junior with their parents copied. - Name a group with toLabel, like Group A. It titles the peek on the count. - Pass onAddGuardian so a junior with no parent on file comes with the fix. - Use audienceReach(to, juniorMessages) for the same count elsewhere, like on a Send button. ### Avoid it for - Picking who a message goes to. This says who it reaches. It does not choose. - A list of people who already read a message. Use Avatar Stack with a count. ### Props - `to`: `{ person: string; photo?: string; id?: string; email?: string; junior?: boolean; guardians?: { person: string; photo?: string; id?: string; email?: string }[] }[]`. Required. Who the message is for. A parent of two juniors is counted once: by id, then email, then name. - `toLabel`: `string`. What the group is called, like Group A. It titles the count's peek. - `juniorMessages`: `"guardians" | "copy"`. Default `"guardians"`. Where messages to juniors go: to their parents instead, or to the junior with their parents copied. - `onAddGuardian`: `(junior: { person: string; photo?: string }) => void`. The fix for a junior with no parent on file, like opening their profile. - `size`: `"sm" | "md" | "lg"`. Default `"md"`. Text and face size: meta, body, or section type. - `className`: `string`. Extra classes on the root. Later classes win. ### Accessibility - Plain text: Goes to, then who. Faces are hidden from screen readers, since the names are in the text. - A group's count is a peek trigger with a dotted underline. Focus or hover opens everyone, grouped by how they get it. - The · before a phrase is hidden from screen readers, which hear a comma instead. When the phrase wraps, the · hides too. - A junior it does not reach is said in danger text, with a button for the fix. It never relies on the color alone. ### Examples #### One person ```tsx ``` #### A junior, through their parents ```tsx ``` #### A group, with a junior who has no parent on file ```tsx openProfile(junior.person)} /> ``` ## Avatar Stack > Overlapping faces for a count of people, one initial each until photos load, with +N past the limit. - Name: `avatar-stack` - Status: beta - Categories: people, display - File: the install writes `avatar-stack.tsx` to your `ui` alias, `@/components/ui` by default. - Other registry items: `@txbrendan/avatar`. The install adds them. - Gallery: https://txbrendan.dev/components/avatar-stack - Registry item: https://txbrendan.dev/r/avatar-stack.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/avatar-stack ``` ### Use it for - Putting faces on a count of people: who is going, who replied, who has seen it. - Pass everyone in people, in order. max sets how many faces show before +N. - Set arrive where people join while the page is open, like check-ins. New faces pop in. The ones already there stay put. - Name everyone in full somewhere people can reach, like a peek on the count. ### Avoid it for - One person. Use Avatar or Person. - A list people must read name by name. Use a list of Person rows. - Faces with no count or label near them. Say what the group is, like 21 going. ### Props - `people`: `{ person: string; photo?: string }[]`. Required. Everyone in the count, in the order given. - `size`: `"sm" | "md" | "lg"`. Default `"md"`. Face size, as Avatar's: 21, 28, or 36px at the default density. - `max`: `number`. Default `5`. Faces shown before +N. - `arrive`: `boolean`. Default `false`. Faces added after the first paint pop in. The rest stay put. - `aria-label`: `string`. The stack's name for screen readers. Defaults to up to three names and how many more, like Sam Carter, Kate Clarke, Josh Tait and 18 more. - `className`: `string`. Extra classes. Set \[--avatar-stack-ring:var(--background)\] when the stack sits on the page, not a card. ### Accessibility - Renders one \. Its name lists up to three people and how many more, so screen readers hear one short line, not every face. - Pass aria-label to say what the group is, like 21 going. - The faces and the +N are hidden from screen readers. Name everyone in full where people can reach them. - The pop only grows and fades. Under reduced motion it only fades. ### Examples #### Who is going ```tsx ``` #### Check-ins that pop in ```tsx "use client"; import { useState } from "react"; import { AvatarStack } from "@/components/ui/avatar-stack"; export function CheckIns() { const [people, setPeople] = useState([{ person: "Sam Carter" }]); return (

); } ``` ## Avatar > A round profile photo that falls back to initials in one of eight soft tints, picked from the name. - Name: `avatar` - Status: beta - Categories: people, display - File: the install writes `avatar.tsx` to your `ui` alias, `@/components/ui` by default. - npm packages: `class-variance-authority`. The install adds them. - Other registry items: `@txbrendan/dither`. The install adds them. - Gallery: https://txbrendan.dev/components/avatar - Registry item: https://txbrendan.dev/r/avatar.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/avatar ``` ### Use it for - Showing who someone is, next to their name: in rows, tables, comments, and cards. - A team or company, with solid set to its own color. - Pass the full name. It names the avatar for screen readers, and it picks the initials and the tint. - Use Person when the name shows beside the avatar. It hides the avatar from screen readers, so the name is read once. ### Avoid it for - A face with no name anywhere near it. A person's name always has their avatar beside it, and the other way round. - Many overlapping faces for a count, like who is going. Use AvatarStack. - A logo or an icon that is not a person or a team. Use the image or the icon itself. - Setting tint to say something, like red for a problem. Tints only tell people apart. - A light solid color, like white or pale yellow. The initials are near white, so they would not show. Use the photo or logo as src. ### Props - `name`: `string`. Required. The full name. It names the avatar and gives the initials and the tint. - `src`: `string`. Photo URL. The initials show until it loads, and stay if it fails. The photo fades in. - `size`: `"sm" | "md" | "lg"`. Default `"md"`. 21, 28, or 36px at the default density. Density scales it. - `tint`: `number`. 0 to 7. Picks a tint instead of the one the name gives. The same name always gets the same tint. - `solid`: `string`. A team's own color, as any CSS color, behind light initials. A thin ring keeps a black or white color off the page. - `initials`: `1 | 2`. Default `2`. How many letters show. Use 1 where faces overlap. - `texture`: `"flat" | "dither" | "gradient" | "grain"`. dither draws the photo as dots over its tint, gradient fades it from the top, and grain speckles it. Initials stay flat. Hover fills gradient and grain in. Left out, the avatar follows the Texture around it. - `className`: `string`. Extra classes. Later classes win, so className='size-16' makes it bigger. ### Accessibility - Renders a \ named by name, so screen readers read the name once and skip the letters. - The photo has an empty alt, since the avatar's own name already says who it is. - When the name shows next to the avatar, pass aria-hidden, or use Person, which does it for you. - The first five tints are the tones' soft pairs, held to 4.5:1 by the theme tests. The other three mix a chart color into the card, and avatar.test.tsx holds their initials to 4.5:1 in light and dark. - A solid color comes from your app, so its contrast is yours to check. The initials use the near-white text color of the solid tones. ### Examples #### With initials ```tsx ``` #### With a photo ```tsx ``` #### A grain photo that clears on hover ```tsx ``` #### A solid brand color ```tsx ``` #### Beside a name ```tsx Josh Tait ``` ## Back Link > A quiet link back to the page above, or a short trail of levels, that sits over a page title. - Name: `back-link` - Status: beta - Categories: navigation - File: the install writes `back-link.tsx` to your `ui` alias, `@/components/ui` by default. - Other registry items: `@txbrendan/breadcrumb`. The install adds them. - Gallery: https://txbrendan.dev/components/back-link - Registry item: https://txbrendan.dev/r/back-link.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/back-link ``` ### Use it for - Put it right above the page title, so people can go up one level: \Schedule\. - Name the page it goes back to, not the word Back. - Pass trail for a short path of levels, like Projects / Mobile app / Settings. The last level is the current page. - With a router, pass its link as render: \}>Schedule\. - With no href and no onClick, it is a button that goes back in the browser history. ### Avoid it for - A long trail of four or more levels. Use Breadcrumb, which can fold the middle into an ellipsis. - The main way around the app. It only goes up one level. - A back button inside a dialog or a step flow. Use a Button there. - Two trails on one page. Each one is a nav named Breadcrumb, so pass a different aria-label to each. ### Props - `href`: `string`. Where the link goes. With no href, it renders a button that runs onClick, or goes back in history. - `children`: `ReactNode`. Default `"Back"`. The name of the page it goes back to, like "Schedule". A chevron sits before it. - `trail`: `{ label: string; href?: string }[]`. Levels in place of one link, joined by slashes. Levels with an href are links. The last level is the current page. - `onClick`: `(event: MouseEvent) => void`. Runs on a click. On the button form, it replaces going back in history. - `render`: `ReactElement`. Renders this element instead of the \, like a router link, with the same props and classes. - `aria-label`: `string`. On a trail, renames its nav from "Breadcrumb". On a link, replaces its name. - `className`: `string`. Extra classes. Later classes win, so className='text-foreground' replaces the muted color. ### Accessibility - The single form is a real \ with an href, or a \ ``` #### Destructive action with a quieter cancel ```tsx

``` #### Loading while a form submits ```tsx "use client"; import { useFormStatus } from "react-dom"; function SubmitButton() { const { pending } = useFormStatus(); return ( ); } ``` #### Icon-only ```tsx import { Trash2 } from "lucide-react"; ``` #### A press that cannot go ahead says why on the button ```tsx "use client"; import { useRef, useState } from "react"; import { Button, shake } from "@/components/ui/button"; function ContinueButton({ ready, onContinue }: { ready: boolean; onContinue: () => void }) { const [asking, setAsking] = useState(false); const timer = useRef>(undefined); return ( <> {asking && ( Fill in your email first. )} ); } ``` #### A link that looks like a button ```tsx import Link from "next/link"; import { buttonVariants } from "@/components/ui/button-variants"; See pricing ``` #### Grain on the lower half, cleared on hover ```tsx ``` ## Calendar > A month grid for picking one date or a range, with keyboard moves, date limits, and names in the user's language. - Name: `calendar` - Status: beta - Categories: dates, forms - File: the install writes `calendar.tsx` to your `ui` alias, `@/components/ui` by default. - Gallery: https://txbrendan.dev/components/calendar - Registry item: https://txbrendan.dev/r/calendar.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/calendar ``` ### Use it for - Picking a date or a range when people need to see the days around it: a booking, a deadline, a trip. - Give the calendar a name: aria-label, like "Check-in", or aria-labelledby with the id of a visible heading. - Values are date strings: "2026-10-20" for one date, and { start, end } of them for a range. A date string has no time and no time zone, so it never moves a day on its way between the browser, the server, and the database. A Date object carries both, which causes off-by-one-day bugs. - It works uncontrolled with defaultValue, even from a server component. Pass value with onValueChange to control it. - In range mode, the first pick sends a one-day range, and the second pick sends the full range. The next pick starts over. - A range people pick never covers a disabled date. After the first pick, days past the nearest one on each side cannot be picked. To start over, pick the first day again. - Set name to send the value with a form: "2026-10-20", or "2026-10-12/2026-10-16" for a range. - The server cannot know the user's date or language. It renders with no today mark, in en-US unless you pass locale, and the browser fills both in after hydration. Pass locale to skip that switch. - With no value, defaultMonth, or month, the server sends a blank grid of the same size, and the browser shows the current month. ### Avoid it for - Dates far from today, like a birth date. Typing is faster there, so use an input. - Picking a time. This calendar picks days only. - Ranges that may cover a disabled date, like a stay over a holiday. After the first pick, a range stops at the nearest one. - Picking many separate dates. It picks one date or one range. ### Props - `mode`: `"single" | "range"`. Default `"single"`. Pick one date, or a start and an end date. - `defaultValue`: `string | { start: string; end: string } | null`. The picked date at first render, as "YYYY-MM-DD". A { start, end } range in range mode. - `value`: `string | { start: string; end: string } | null`. Controlled value. Use it with onValueChange. - `onValueChange`: `(value: string | { start: string; end: string }) => void`. Called with the new value on each pick. - `min`: `string`. The earliest date people can pick, as "YYYY-MM-DD". Earlier days are disabled, and focus stops there. - `max`: `string`. The latest date people can pick. Later days are disabled, and focus stops there. - `disabledDates`: `string[] | ((date: string) => boolean)`. Days people cannot pick. They can still get focus, and a range people pick cannot cross one. A function only works from a client component. - `disabled`: `boolean`. Default `false`. Blocks picking and moving, and takes the calendar out of the tab order. - `weekStartsOn`: `0 | 1 | 2 | 3 | 4 | 5 | 6`. The first column: 0 is Sunday, 1 is Monday. Defaults to the locale's custom. - `locale`: `string`. A language tag for month and day names, like "de-DE". Defaults to the browser's language. - `defaultMonth`: `string`. The month on screen at first render, as "YYYY-MM". Defaults to the picked date's month, or today's. - `month`: `string`. Controlled month, as "YYYY-MM". Use it with onMonthChange. - `onMonthChange`: `(month: string) => void`. Called with the new "YYYY-MM" when the month on screen changes. - `size`: `"sm" | "md" | "lg"`. Default `"md"`. Day size and text size. Days are as tall as controls of the same size. Density scales them. - `tone`: `"neutral" | "brand" | "danger" | "success" | "warning"`. Default `"neutral"`. Color of the picked days. - `name`: `string`. Form field name. Sends "YYYY-MM-DD", or "YYYY-MM-DD/YYYY-MM-DD" for a range. - `aria-label`: `string`. Names the calendar, like "Check-in". TypeScript requires this or aria-labelledby. The grid is already named by the month. - `aria-labelledby`: `string`. The id of a visible heading that names the calendar. Use it in place of aria-label. - `className`: `string`. Classes for the outer box. Later classes win, so className='p-0' drops the padding. ### Accessibility - TypeScript requires aria-label or aria-labelledby, so screen readers say what the date is for. - The days form a grid (role="grid") named by the month title. Each day is a gridcell named with its full date, like "Tuesday, October 20, 2026", in the calendar's language. - Weekday headers show short names, or one letter in languages whose short names are long, like Arabic. Each header keeps the full day name in its abbr attribute. - One day is in the tab order: the last focused day, else the picked day, else today, else the first day of the month. - Arrow keys move by day and by week. Home and End go to the start and end of the week. Page Up and Page Down move by month, and with Shift by year. Enter or Space picks the day. - Left and Right Arrow swap in right-to-left text, when a parent has dir="rtl". - Picked days have aria-selected, today has aria-current="date", and days people cannot pick have aria-disabled. - Disabled dates can still get focus, so people can hear them, but they cannot be picked. Days outside min and max cannot get focus. - In range mode, after the first pick, days past the nearest disabled date get aria-disabled until the second pick. They can still get focus, but Enter and clicks do nothing there. - The month buttons are named by the month they show, like "November 2026", so their names follow the locale. At min or max they set aria-disabled and keep focus. - The month title is a polite live region, so screen readers hear the new month. - Picked days use the tone's solid pair, and days inside a range use its soft pair. The theme tests hold both to 4.5:1. - Hovered days use the accent pair, and weekday names use muted text. The theme tests hold both to 4.5:1. The focus ring uses --ring, held to 3:1 on the page and cards. - Days people cannot pick are dimmed to half strength, and days from disabledDates are also struck through. - On a screen narrower than the calendar, the days get narrower to fit, so the page never scrolls sideways. ### Examples #### Pick a date ```tsx ``` #### A range between two limits ```tsx ``` #### Days people cannot pick ```tsx ``` #### Controlled, in one language ```tsx "use client"; import { useState } from "react"; function DueDate() { const [date, setDate] = useState(null); return ; } ``` #### No weekends, from a client component ```tsx "use client"; // A "YYYY-MM-DD" string parses as midnight UTC, so getUTCDay gives its weekday. const weekend = (date: string) => [0, 6].includes(new Date(date).getUTCDay()); function MeetingDay() { return ; } ``` #### Show a picked date ```tsx // Format in UTC, the zone a date string parses in, so the day never moves. const label = new Intl.DateTimeFormat("en-US", { dateStyle: "medium", timeZone: "UTC" }).format( new Date("2026-10-20"), ); // "Oct 20, 2026" ``` ## Call To Action > A next step offered in a card: a scene that shows it, what it is, why, how far along you are, and the step itself. - Name: `call-to-action` - Status: beta - Categories: actions - File: the install writes `call-to-action.tsx` to your `ui` alias, `@/components/ui` by default. - npm packages: `lucide-react`. The install adds them. - Other registry items: `@txbrendan/button`, `@txbrendan/card`, `@txbrendan/icon`, `@txbrendan/ring-progress`, `@txbrendan/tool-button`. The install adds them. - Gallery: https://txbrendan.dev/components/call-to-action - Registry item: https://txbrendan.dev/r/call-to-action.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/call-to-action ``` ### Use it for - Where the space would sit empty otherwise: a workspace still setting up, a feature nobody has tried yet. - title says what the step is. text says why, in a line or two. Put a Scene in scene to show it. - main is the step itself, a primary button with its icon. later is the quiet way out: "Skip" or "Later". - Pass progress, like { done: 3, of: 4 }, when the step is one of a set. - Give main a result, like { label: "Invites sent", onUndo, onCommit }, to show what the press did on the button, with Undo for 8 seconds. ### Avoid it for - More than one on a screen. - Warnings or news. Use an alert. - Steps people can't skip. Put them in the page's flow. ### Props - `title`: `string`. Required. What the step is: "Invite your team". It names the card for screen readers. - `text`: `ReactNode`. Why, in a line or two. - `scene`: `ReactNode`. A Scene, inset 6px from the card's edge. - `progress`: `{ done: number; of: number }`. How far along a set of steps is: a small ring and "3 of 4". - `main`: `{ label: string; icon?: IconName | ReactNode; onClick?: () => void | Promise; result?: ActionResult; loading?: boolean; disabled?: boolean }`. Required. The step itself: a brand button with its icon. icon is a name from Icon's set or any icon. A returned promise shows it's busy. - `later`: `{ label: string; onClick?: () => void }`. The quiet way out, a ghost button before the step. - `className`: `string`. Extra classes on the card. Later classes win. ### Accessibility - The card is a region named by its title. - Tab goes to the way out, then the step. Both are buttons. - Progress reads as "3 of 4 done". The ring is hidden, since the words say it. - A result changes the step's own name, like "Invites sent. Press to undo.", and is said in a polite live region. - Undo only undoes once 1.2 seconds have passed, so a double press never undoes. ⌘Z takes it back too. ### Examples #### With progress, a way out, and Undo ```tsx import { UserPlus } from "lucide-react"; } label="Invite people" /> } title="Invite your team" text="They see the plan and pick up work, without asking you." progress={{ done: 3, of: 4 }} later={{ label: "Skip", onClick: () => console.log("skip") }} main={{ label: "Invite people", icon: , result: { label: "Invites sent", onUndo: () => {}, onCommit: () => console.log("send invites") }, }} /> ``` ## Card Field > Card details as one group: the number, the expiry (MM / YY), and the security code, with one line of help or error under it. The number groups itself as it is typed and names the brand in words. - Name: `card-field` - Status: beta - Categories: forms - File: the install writes `card-field.tsx` to your `ui` alias, `@/components/ui` by default. - Other registry items: `@txbrendan/field-frame`, `@txbrendan/input`, `@txbrendan/status-text`. The install adds them. - Gallery: https://txbrendan.dev/components/card-field - Registry item: https://txbrendan.dev/r/card-field.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/card-field ``` ### Use it for - Taking a card to pay for an order, a plan, or a booking. - It is the look and the checks, for demos and prototypes. In production, use the payment provider's own hosted fields, so card numbers never reach your server. - Set showErrors when Pay is pressed, rather than disabling Pay. Every problem then shows at once. - When the bank says no, pass declined with why, like "Nothing was taken.", and onRetry. Clear it when the details change. - Offer saved cards as selection cards above it, and this field for a new one. ### Avoid it for - Sending card numbers to your own server. Use the payment provider's hosted fields. - Bank details or other numbers. Use an input. - Showing a saved card. Show its brand and last four digits as text. ### Props - `value`: `{ number: string; expiry: string; cvc: string }`. The parts as typed, like "4242 4242 4242 4242", "12 / 28", and "123". Pass it with onValueChange to control the field. - `defaultValue`: `Partial`. The parts to start with, when the field keeps its own value. - `onValueChange`: `(value: CardValue, info: { brand: "Visa" | "Mastercard" | "Amex" | null; last4: string; complete: boolean }) => void`. Called on each change, with the brand, the last four digits, and whether every part is complete and right. - `label`: `ReactNode`. Names the group, above it. Pressing it focuses the number. Without one, the group is named "Card details". - `hint`: `ReactNode`. A short note under the group. - `error`: `ReactNode`. Other problems, in red under the group, with red rings on every part. - `showErrors`: `boolean`. Default `false`. Shows every problem, empty parts too. Set it when Pay is pressed. - `declined`: `boolean | string`. The bank declined it. "Declined" shows in red, then the string says why, in ink. - `onRetry`: `() => void | Promise`. With declined: a retry icon ending the line, named "Try again". Return a promise, and it waits on it. - `today`: `string`. Today for the expiry check, as "2026-09-29", for demos and tests. Default: the browser's today, once the field is on the page. - `size`: `"sm" | "md" | "lg"`. Default `"md"`. Height, padding, and text size of every part. - `disabled`: `boolean`. Default `false`. Turns every part off. - `ref`: `Ref`. Reaches the card number input, where focus starts. - `id`: `string`. Lands on the group, with aria-\* and data-\. Its aria-describedby joins the note's. - `className`: `string`. Classes for the frame around the label, the group, and the note. ### Accessibility - The three parts sit in a group named by the label, or "Card details". - Each part has its own name: "Card number", "Expiry date, MM / YY", and "Security code". - The brand shows in words, never a logo, and describes the number input. It is said politely when it changes. - A part with a problem is marked invalid and described by the note under the group, which is announced when it appears. - Focus moves on once a part is complete and right. Backspace in an empty part goes back to the one before. - The parts use the browser's card autofill and a number keypad, and take no name, so a plain form never posts the digits. ### Examples #### Start with a test card ```tsx ``` #### The bank declined it ```tsx {}} today="2026-09-29" /> ``` ## Card > A bordered surface that groups related content, with header, title, description, content, and footer parts. - Name: `card` - Status: beta - Categories: layout - File: the install writes `card.tsx` to your `ui` alias, `@/components/ui` by default. - Gallery: https://txbrendan.dev/components/card - Registry item: https://txbrendan.dev/r/card.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/card ``` ### Use it for - Grouping one topic so it reads as a unit: a plan, a stat, a settings section, a list item with actions. - Laying out several items of the same kind in a grid. - Use only the parts you need. A card with just CardContent is fine. - Density sets the padding and the space between parts, so cards tighten and loosen with the rest of the app. ### Avoid it for - Wrapping the whole page, or putting cards inside cards. Use headings and spacing instead. - Important messages. Use an Alert, so the message has a tone. - Making the whole card a click target with onClick on the div. Put a real link or button inside it. - Rows of a table. Use a table, so screen readers can move by row and column. ### Props - `className`: `string`. Extra classes on any part. Later classes win, so className='px-0' on CardContent lets a table run edge to edge. - `Card`: `ComponentProps<"div">`. The surface. Pads top and bottom with --space-inset and spaces its parts with --space-stack. - `CardHeader`: `ComponentProps<"div">`. Part. Stacks the title and description. - `CardTitle`: `ComponentProps<"div">`. Part. Semibold title. A div, so put an \
or \
inside when the card needs a heading. - `CardDescription`: `ComponentProps<"div">`. Part. Secondary text in muted-foreground. - `CardContent`: `ComponentProps<"div">`. Part. The body. Pads its sides with --space-inset. - `CardFooter`: `ComponentProps<"div">`. Part. A row for actions or a summary. It wraps on small screens. ### Accessibility - Every part is a plain \
with no role, so a card adds no noise for screen readers. - CardTitle is not a heading. Put an \
or \
inside it at the right level when people should be able to jump between cards. - Keep links and buttons inside the card. A clickable div is not reachable by keyboard. - The theme tests hold card-foreground and muted-foreground to 4.5:1 on the card color, in light and dark. ### Examples #### Header, content, and footer (needs @txbrendan/button) ```tsx import { Button } from "@/components/ui/button"; Pro plan For teams that ship every week.
$24 per month
``` #### A stat with only content ```tsx
Active users

12,480
``` #### A heading inside the title ```tsx
Billing
Your next invoice is on 1 November. ``` #### A list that runs edge to edge ```tsx Recent deploys

main · 2 minutes ago

fix-login · 1 hour ago

``` ## Champion Card > The champion's slot: a dashed "Winner to be decided" until crowned, then a warm card that springs in with sparkles and 3 seconds of confetti. - Name: `champion-card` - Status: beta - Categories: sport, display - File: the install writes `champion-card.tsx` to your `ui` alias, `@/components/ui` by default. - npm packages: `lucide-react`. The install adds them. - Other registry items: `@txbrendan/motion-timing`. The install adds them. - Gallery: https://txbrendan.dev/components/champion-card - Registry item: https://txbrendan.dev/r/champion-card.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/champion-card ``` ### Use it for - The end of a bracket or a finals board, where the winner goes. - Leave champion out until the final is decided. Then pass { name }, and the card springs in. - Pass celebrate={false} for a past winner, so a page that loads already crowned throws no confetti. - Use subtitle to say what they won, like "Cup winners 2026". It replaces the Champion badge. - Set the width with className. It is 200px by default. ### Avoid it for - Ordinary results, like a match winner. Keep the confetti for the one champion. - More than one on a page, since each throws its own confetti. ### Props - `champion`: `{ name: string } | null`. Who won. null or left out until the winner is decided. - `subtitle`: `string`. Default `"Champion"`. The badge on the crowned card. - `celebrate`: `boolean`. Default `true`. Throws confetti when crowned. false crowns it without. - `className`: `string`. Extra classes on the root. Set the width here, like w-64. Later classes win. ### Accessibility - The root is a polite live region, so crowning it while someone is on the page says the winner's name and badge. - The trophy, sparkles, and confetti are hidden from screen readers. - Under reduced motion the card and its sparkles only fade in, and it throws no confetti. With motion off, it crowns in place. - The crowned card's text is the warning tone's soft text on its soft fill, and the badge is its solid pair. The theme holds both to 4.5:1. - The confetti never takes a press. ### Examples #### Before the final ```tsx ``` #### Crowned ```tsx ``` #### A past winner, with no confetti ```tsx ``` ## Chart Key > A key for a chart's title row that shows the point under the pointer, with numbers that roll as it moves. Area Chart, Bar Chart, and Line Chart use it for legend="top". - Name: `chart-key` - Status: beta - Categories: charts - File: the install writes `chart-key.tsx` to your `ui` alias, `@/components/ui` by default. - npm packages: `recharts`, `react-is`. The install adds them. - Other registry items: `@txbrendan/chart`, `@txbrendan/glide-highlight`, `@txbrendan/morph-label`, `@txbrendan/motion-timing`, `@txbrendan/rolling-number`, `@txbrendan/skeleton`. The install adds them. - Gallery: https://txbrendan.dev/components/chart-key - Registry item: https://txbrendan.dev/r/chart-key.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/chart-key ``` ### Use it for - A chart that shows its values in the title row in place of a tooltip box. Pass legend="top" to Area Chart, Bar Chart, or Line Chart, which use this for you. - A chart of your own on the chart base. Call useChartKey, pass its key as the Chart's legendContent, set legendPosition to "top", and put ChartKeyTracker inside the Recharts chart. - Each series in the key is a button that hides or shows it. Give each series' layer keySeriesClass(hidden.has(key)) so it fades, and tooltipType="none" while hidden. In a stack, pass the data through withoutHidden(data, gone), so the rest close the gap once it has faded. ### Avoid it for - A chart people read point by point with many series. Past three series the key wraps, and a tooltip by the pointer is easier to read. - Charts with no order on the x axis, like a donut. The key follows the point under the pointer along the x axis. ### Props - `useChartKey`: `(options: { data; categoryKey; series; valueFormat?; locale? }) => { key; point; hidden; gone }`. Hook. Builds the key for the Chart's legendContent, and the point to pass to ChartKeyTracker. At rest it shows the last point. hidden holds the series turned off in the key. gone holds those whose fade has ended. - `ChartKeyTracker`: `({ point }) => null`. Put it inside the Recharts chart. It tells the key which point is under the pointer or the keyboard. It draws nothing. - `keySeriesClass`: `(hidden: boolean) => string`. Classes for a series' layer, so a hidden one fades out where it is over --motion-duration-base. - `withoutHidden`: `(data, gone) => data`. The data with each series in gone at zero, for a stacked chart. Recharts glides the stack to its new shape. ### Accessibility - The key sits beside the chart's title, not in it, so the chart's name never changes as the key moves. - Each value holds the width of its longest one, so the key stays still as its numbers roll. Each number keeps its full text for screen readers. - Keep the chart's tooltip on the page with the sr-only class, so the keyboard layer still reads each point out. - Each series is a toggle button with aria-pressed. Hidden, its swatch empties to an outline and its value dims, and nothing changes size. The last series shown is aria-disabled, so the plot never goes blank. - One highlight glides between the buttons as the pointer moves, and a press darkens it. Each button shows the focus ring from the keyboard. - The digits roll on the motion variables. With motion off or reduced, they change at once. - While the chart loads, each value holds a placeholder and the buttons are aria-disabled. When the values land, the buttons glide to their new places. With motion off or reduced, they move at once. ### Examples #### Key beside the title, on a line chart ```tsx ``` ## Chart > The base every chart builds on: a frame that holds its height, theme series colors, a themed tooltip and legend, and loading, empty, and error views. - Name: `chart` - Status: beta - Categories: charts - File: the install writes `chart.tsx` to your `ui` alias, `@/components/ui` by default. - Other registry items: `@txbrendan/button`, `@txbrendan/motion-timing`, `@txbrendan/skeleton`. The install adds them. - Gallery: https://txbrendan.dev/components/chart - Registry item: https://txbrendan.dev/r/chart.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/chart ``` ### Use it for - Building a chart we do not ship, like a scatter or radar chart, so it looks and behaves like the others. - Put the Recharts chart inside Chart's render function. Spread \`name\` on the chart, \`animation\` on each series, and \`tooltipAnimation\` on the Tooltip. - Wrap the Recharts chart in Recharts' AnimationControllerProvider with \`animationController\`, so it draws in once it is on screen and ends drawn when the page prints. - Pass \ as a Recharts Tooltip's content for a tooltip in theme colors. - Use chartSeries(config) for each series' label and color, and chartColor(i) for a single color. - Spread chartAxisProps on each axis and chartGridProps on the grid, so they match the charts we ship. - Pass a skeleton that looks like your chart, so it loads in its own shape. If you build your own legend, call useChartLegendGlide(ref, waiting) so its items glide when values land. ### Avoid it for - A bar, line, area, or donut chart. Use BarChart, LineChart, AreaChart, or DonutChart. They already use this frame. - A small trend inside a table cell or next to a number. Use Sparkline. - A single number. Show the number in text. - More than five series. The theme has five chart colors, and a sixth series repeats the first color. ### Props - `title`: `ReactNode`. A visible title, shown as the figure's caption. It names the chart. - `aria-label`: `string`. Names the chart when it has no visible title. TypeScript requires title, aria-label, or aria-labelledby. - `size`: `"sm" | "md" | "lg"`. Default `"md"`. Height: 5, 7, or 9 times --control-h-md, so density scales it. Every state keeps it. - `loading`: `boolean`. Default `false`. Shows a loading shape at the same height and sets aria-busy on the plot area. When data arrives, the shape fades out while the chart draws under it. - `loadingText`: `string`. Default `"Loading chart"`. Read out to screen readers while loading. - `error`: `ReactNode`. Shows this message in place of the chart. true shows "The chart could not load." - `onRetry`: `() => void`. Shows a retry button under the error. - `retryText`: `string`. Default `"Try again"`. The retry button's text. - `empty`: `boolean`. Default `false`. True when there is nothing to draw. Shows emptyText. - `emptyText`: `ReactNode`. Default `"No data yet"`. Shown when the chart is empty. - `legend`: `{ key: string; label: ReactNode; color: string; value?: ReactNode }[]`. Legend entries, shown under the chart while it loads and once it draws. - `skeleton`: `"bars" | "area" | "line" | "dots" | "points" | "ring"`. Default `"bars"`. The loading shape. Pick the one that looks like the chart: area, line, dots for a swarm, points for a scatter, ring for a pie or donut. - `children`: `({ animation, tooltipAnimation, animationController, name }) => ReactNode`. Draws the chart once it is ready. Leave it out to show only the frame and its states. - `className`: `string`. Extra classes. Later classes win, so className='h-96' replaces the height. ### Accessibility - Renders a \
. A title becomes its \
, which names the figure and the chart's SVG. TypeScript requires title, aria-label, or aria-labelledby. - Keeps one height in every state, set in CSS, so the page does not move when data arrives. The height is in the server HTML. When the page prints, it asks the browser to keep a chart that fits on one page whole. In the light theme, it asks the browser to print legend dots and loading shapes even with backgrounds off. - While loading, the plot area has aria-busy and the loading shapes are hidden from screen readers. With motion off, the shape goes at once. Reduced motion keeps the fade. - A role="status" line stays on the page outside the plot area. It reads out loading, the error, and the empty text when they are plain text. - The error view shows a retry Button when you pass onRetry, so keyboard users can try again. - Recharts' keyboard layer stays on: the chart's SVG is one tab stop, the arrow keys move between points, and the tooltip reads each point out. - The SVG takes the focus-ring style, so keyboard focus shows on the chart. - Series colors default to --chart-1 through --chart-5. The theme tests hold each to 3:1 against the page background, in light and dark. The legend and tooltip also name each series in text. - Series draw in over three times --motion-duration-base, and only once the chart is on screen. A chart off screen waits with no timer running. When the page prints, every series jumps to its last frame, even in a chart never seen. The tooltip moves over --motion-duration-base. At 0ms, motion off, charts draw with no animation. Recharts also skips animation when the system asks for reduced motion. ### Examples #### A chart we do not ship, on the frame ```tsx "use client"; import { AnimationControllerProvider, CartesianGrid, Scatter, ScatterChart, Tooltip, XAxis, YAxis } from "recharts"; import { Chart, ChartTooltipContent, chartAxisProps, chartColor, chartGridProps } from "@/components/ui/chart"; const homes = [ { size: 80, price: 210 }, { size: 120, price: 290 }, { size: 160, price: 410 }, { size: 210, price: 520 }, ]; export function PriceBySize() { return ( {({ animation, tooltipAnimation, animationController, name }) => ( } cursor={{ stroke: "var(--input)" }} {...tooltipAnimation} /> )} ); } ``` #### Loading, empty, and error ```tsx refetch()} /> ``` #### A legend and a tooltip in theme colors ```tsx import { ChartLegend, ChartTooltipContent, chartSeries } from "@/components/ui/chart"; const series = chartSeries({ desktop: { label: "Desktop" }, mobile: { label: "Mobile" } }); } /> ``` ## Check-in Code > An event's check-in code, for a host's phone or a tablet at the door. Faces arrive under it as people scan, and the count opens who is not in yet. - Name: `check-in-code` - Status: beta - Categories: data, display - File: the install writes `check-in-code.tsx` to your `ui` alias, `@/components/ui` by default. - Other registry items: `@txbrendan/avatar-stack`, `@txbrendan/hover-card`, `@txbrendan/peek-card`, `@txbrendan/qr-code`, `@txbrendan/rolling-number`. The install adds them. - Gallery: https://txbrendan.dev/components/check-in-code - Registry item: https://txbrendan.dev/r/check-in-code.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/check-in-code ``` ### Use it for - On a host's phone or a tablet at the door, as people arrive for a workshop or a meeting. - Pass value, usually the event's check-in link. The code is drawn on the device, so it shows without signal. - Pass code too, a short one to type, so nothing is camera-only. Digits are easiest on a phone keypad. - Pass checkedIn, oldest first, and expected. The count rolls and is read out, and reads All 23 checked in, in green, once everyone is in. - Pass notYet and onCheckIn, and each Not yet row in the count's peek gets Check in, for anyone without a phone or with a flat battery. Their face arrives at once, Undo takes it back for 8 seconds, and onCheckIn runs once the window ends. - Change value to rotate the code. The new one fades in. - Use layout="side" on a wide screen, with the code on the left and the details on the right. ### Avoid it for - A toast for each check-in. The face arriving and the row turning to Checked in already say it. - Telling people the count by color alone. All 23 checked in says it in words. ### Props - `value`: `string`. What the code opens, usually the event's check-in link. - `title`: `string`. The event, like "Workshop". It names the code and the peek. - `meta`: `string`. When and where, like "Tue 6 Oct · 19:00 · Room 1". - `hint`: `string`. Default `"Scan with your phone camera to check in"`. What to do with the code. - `code`: `string`. A short code to type instead, like "482 719". - `checkedIn`: `{ person: string; photo?: string; at?: string | Date }[]`. Who has checked in, oldest first. - `expected`: `number`. How many are expected. - `notYet`: `{ person: string; photo?: string; meta?: string }[]`. Who has not checked in yet, for the peek. - `onCheckIn`: `(person: { person: string; photo?: string }) => void | Promise`. Adds Check in to each Not yet row in the peek. It runs once the undo window ends. - `peek`: `Partial`. More PeekCard props for the count's peek, like actions: \[{ label: "Remind 9" }\]. - `size`: `"sm" | "md" | "lg"`. Default `"md"`. The code's size: 120, 160, or 240px. Use "lg" on a tablet at the door, so it scans from further off. - `layout`: `"stack" | "side"`. Default `"stack"`. The code in the middle, or the code left and the details right. - `className`: `string`. Extra classes. Later classes win. ### Accessibility - The code is an image named "Check-in code for" and the title. - The short code is text, so people can read it out or type it. - The count is a peek trigger. Hover, focus, or a tap opens who is not in yet, then who is in, and Esc closes it. - A polite live region reads the count each time it changes, like "15 of 23 checked in". - The faces are hidden from screen readers. The count and the peek say who is in. - Check in is a native button that slips to Checked in, with Undo, and says so once. - All 23 checked in is green text in the success tone's soft text, which the theme holds to 4.5:1, and the words say it too. ### Examples #### Large code, with a code to type and the count ```tsx ``` ## Checkbox > A box people tick to pick an option, with a built-in label, tones, sizes, and a mixed state. - Name: `checkbox` - Status: beta - Categories: forms - File: the install writes `checkbox.tsx` to your `ui` alias, `@/components/ui` by default. - npm packages: `@base-ui/react`, `class-variance-authority`. The install adds them. - Gallery: https://txbrendan.dev/components/checkbox - Registry item: https://txbrendan.dev/r/checkbox.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/checkbox ``` ### Use it for - Picking any number of options from a list, like topics to follow. - Agreeing to something before a form is sent, like the terms of service. - Pass the label text as children. The box and the text share one label, so clicking either one toggles it. - When the text has to sit apart from the box, give the box an id and point a label's htmlFor at it. - A 'select all' box above a list. Set indeterminate when only some items are picked, and it shows the mixed state. ### Avoid it for - A setting that takes effect right away. Use a switch. - Picking exactly one option from a list. Use a radio group. - Options with a hint, a price, or a consequence. Use SelectionGroup multiple with a SelectionCard for each. - An id with no label pointing at it. TypeScript accepts the id, but the box then has no name. ### Props - `children`: `ReactNode`. Visible label text. Without it, TypeScript requires aria-label, aria-labelledby, or an id. - `id`: `string`. Links a separate label. A label whose htmlFor matches names the box, and clicking it toggles the box. - `tone`: `"neutral" | "brand" | "danger" | "success" | "warning"`. Default `"neutral"`. Color of the checked box. - `size`: `"sm" | "md" | "lg"`. Default `"md"`. Box size and label text size. Density scales them. - `checked`: `boolean`. Controlled state. Use it with onCheckedChange. - `defaultChecked`: `boolean`. Default `false`. Starting state when you do not control it. - `onCheckedChange`: `(checked: boolean, details) => void`. Called with the new state when someone toggles the box. - `indeterminate`: `boolean`. Default `false`. Shows a dash and sets aria-checked to mixed. - `disabled`: `boolean`. Default `false`. Blocks toggling and removes the box from the tab order. The label text dims too. - `name`: `string`. Form field name. The box sends its value with the form when checked. - `aria-invalid`: `boolean`. Shows the danger border. Set it when validation fails, and link the message with aria-describedby. - `className`: `string`. Classes for the box. Later classes win, so className='\[--checkbox-size:1.5rem\]' makes it bigger. ### Accessibility - Renders a span with role="checkbox" plus a hidden native checkbox, so the value is sent with the form. - Space toggles it. Enter does not toggle it. Enter submits the form, as it does on a native checkbox. - TypeScript requires visible children, aria-label, aria-labelledby, or an id. It cannot check that a label points at the id. - In server HTML, only aria-label and aria-labelledby name the box. A label from children or an id is linked once JavaScript runs. - Clicking the label text also toggles the box, so the target is bigger than the box. - The unchecked border uses --input and the focus ring uses --ring. The theme tests hold both to 3:1 against the page and cards. - The check mark uses the tone's foreground on its fill, which the theme tests hold to 4.5:1. - Press scale and the check mark's pop-in follow --motion-\ tokens. Reduced motion turns both off and keeps the fade. ### Examples #### With a label ```tsx I accept the{" "} terms of service ``` #### A list of options ```tsx
Email me about New releases Tips and guides Events near me
``` #### Select all, with the mixed state ```tsx "use client"; import { useState } from "react"; const files = ["report.pdf", "notes.txt", "photo.png"]; function FilePicker() { const [picked, setPicked] = useState(["report.pdf"]); const all = picked.length === files.length; return (

Files
0 && !all} onCheckedChange={(checked) => setPicked(checked ? files : [])} > Select all
{files.map((file) => ( setPicked((now) => (checked ? [...now, file] : now.filter((f) => f !== file)))} > {file} ))}

); } ``` #### Controlled ```tsx "use client"; import { useState } from "react"; function MarketingConsent() { const [checked, setChecked] = useState(false); return ( Send me product news ); } ``` #### No visible text, in a table row ```tsx ``` #### Named by a separate label ```tsx
Join the beta
``` ## Chip Glide > Moves a wrapping row of chips when values come and go. A removed chip fades where it sits, then the others glide to their new places. It shows nothing. - Name: `chip-glide` - Status: beta - Categories: motion, forms - File: the install writes `chip-glide.tsx` to your `ui` alias, `@/components/ui` by default. - npm packages: `@base-ui/react`. The install adds them. - Other registry items: `@txbrendan/motion-timing`. The install adds them. - Gallery: https://txbrendan.dev/components/chip-glide - Registry item: https://txbrendan.dev/r/chip-glide.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/chip-glide ``` ### Use it for - A row of chips that people add to and remove from, like Token Field and Combobox with multiple. - Make a leaving chip inert, so a press passes through it. Give the box content-start, so its lines stay put while it glides to a new height. - rows and box alone glide the chips. hold and tip keep the pressed remove button in place and give it its tooltip. ### Avoid it for - A list that changes all at once, like search results. Fade the new list in. - Rows that reorder by drag. Use a reorder list. ### Props - `useChipGlide`: `(values: readonly string[]) => { rows, box, hold, tip }`. Hook. Pass the values in order. Returns the rows to render, the props for the wrapping box, and hold and tip for each remove button. - `rows`: `{ value: string; leaving: boolean }[]`. What to render, in order. A removed value stays, leaving, until it has faded. - `box`: `{ ref, onPointerMove, onPointerLeave }`. Spread on the element that wraps the chips and the text field. Put data-glide on each chip, set to its value, data-glide="" on the text field, and data-spot on each remove button. - `hold`: `(value: string) => (event: PointerEvent) => void`. The remove button's onPointerDown. A mouse holds the removed chip in place, faded, until it moves off the button. A finger does not. - `tip`: `(value: string) => { handle, id }`. The remove button's tooltip. Spread it on the TooltipTrigger, and render one Tooltip per row, outside the chips, with this handle. It fades out where its chip was. ### Accessibility - A leaving chip is inert and hidden from screen readers while it fades, so it is never read twice or pressed. - A press where a held chip was lands on the box behind it, not on the next chip or the text field. - A chip removed from the keyboard hands focus to the next chip's remove button, or the one before it. - Reduced motion keeps the fades, and puts each chip in its new place at once. Motion off does both at once. ### Examples #### Remove chips and glide the rest (needs @txbrendan/tooltip) ```tsx function Labels({ values, onRemove }: { values: string[]; onRemove: (value: string) => void }) { const glide = useChipGlide(values); return (
{glide.rows.map(({ value, leaving }) => ( {value} onRemove(value)}> × ))} {glide.rows.map(({ value }) => ( Remove {value} ))}
); } ``` ## Choice Chips > Pills for short tags, like teams, plans, and days of the week. Pick several by default, with a check that springs in, or pick one with the arrow keys. - Name: `choice-chips` - Status: beta - Categories: forms - File: the install writes `choice-chips.tsx` to your `ui` alias, `@/components/ui` by default. - Other registry items: `@txbrendan/field-frame`. The install adds them. - Gallery: https://txbrendan.dev/components/choice-chips - Registry item: https://txbrendan.dev/r/choice-chips.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/choice-chips ``` ### Use it for - Short tags only: teams, plans, days of the week. One or two words each. - Pick several by default. Each chip is a checkbox, a Tab stop of its own, and Space ticks it. - Pass multiple={false} to pick one. The chips become a radio group: one Tab stop, and the arrows move and choose. - In a single choice, pressing the chosen chip again clears it, so the value can be null. - Set max to cap how many can be picked. Say the cap in the label, like "Teams · up to 3". The rest dim once it is reached. - Set error when the form is sent with nothing picked, like "Pick at least one team". ### Avoid it for - An option with a hint, a price, or a consequence. Use a selection card. - A long list, or one people search. Use a combobox. - Turning one setting on or off. Use a switch. - Free tags people make up. These chips only offer the options you pass. ### Props - `options`: `Array`. The chips. A string is its own id and label. count shows a muted number after the label. - `multiple`: `boolean`. Default `true`. Pick several, as checkboxes. false picks one, as a radio group, and value becomes one id or null. - `value`: `string[] | string | null`. The ids picked: an array, or one id or null when multiple is false. Use it with onValueChange. - `defaultValue`: `string[] | string | null`. The ids picked at first render, when you do not control them. - `onValueChange`: `(value: string[] | string | null) => void`. Called with the ids picked, or with one id or null when multiple is false. - `max`: `number`. Most that can be picked. Once it is reached, the rest dim and do nothing when pressed. - `label`: `ReactNode`. Names the group, above it. Pressing it focuses the group's Tab stop. - `hint`: `ReactNode`. A short note under the chips. It describes the group. - `error`: `ReactNode`. Replaces the hint, in red, rings the open chips in red, and is announced once. - `size`: `"sm" | "md" | "lg"`. Default `"md"`. Chip height and text size: 28, 32, or 36px at the default density. - `disabled`: `boolean`. Default `false`. Blocks every chip, and dims the label. - `className`: `string`. Classes for the frame. id, ref, and aria-\* land on the group. ### Accessibility - Several answers: a group of checkboxes. Each chip is a Tab stop, and Space ticks it. - One answer: a radio group. Tab lands on the chosen chip, or the first. The arrows move and choose, and wrap. Home and End jump to the ends. - The label names the group, and the hint or error describes it. An error is announced once when it appears. - Once max is reached, the rest are aria-disabled, so they stay findable with the keys. - Focusing the group itself, as a form does with its first error, moves focus to its Tab stop. - A chosen chip shows by its fill and, with several answers, a check. In forced-colors mode, where fills are gone, a single answer shows the check too. ### Examples #### Several answers ```tsx ``` #### One answer ```tsx ``` ## Choice Poll > A question with options people pick one of. After a vote, it shows each option's share as a bar with a percent and a count. - Name: `choice-poll` - Status: beta - Categories: forms, voting - File: the install writes `choice-poll.tsx` to your `ui` alias, `@/components/ui` by default. - npm packages: `@base-ui/react`. The install adds them. - Other registry items: `@txbrendan/motion`, `@txbrendan/button`, `@txbrendan/badge`. The install adds them. - Gallery: https://txbrendan.dev/components/choice-poll - Registry item: https://txbrendan.dev/r/choice-poll.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/choice-poll ``` ### Use it for - Asking a group one question with a few fixed answers, like which day suits a meeting. - Pass every option with its votes so far. The poll works out each share and the total. - It has three states. Open: people pick one option and press Vote. Voted: it shows the results. Closed: voting has ended and it shows the final results. - Return a promise from onVote to save the vote. The results show at once, with savingText on this person's choice, until the promise settles. If it rejects, the choices come back with the pick still made, and errorText says the vote did not save. - While a vote saves, the choices are gone, so no one can start a second vote. The root has data-pending until the save settles. - Leave vote out to let the poll keep its own state. It then counts the vote it takes, and defaultVote marks an earlier vote. - Pass vote to keep the vote in your own state. Set it to null until this person has voted. Once the save succeeds, and before your onVote promise resolves, set vote to their choice and add it to the votes you pass. - For another language, pass voteText, yourVoteText, savingText, errorText, closedText, requiredText, votesText, and locale. ### Avoid it for - Questions where people can pick more than one answer. Use checkboxes instead. - Letting people change their vote. Once someone votes, the poll shows results and the choices are gone. - Ranking a long list of ideas that people add to. Use Feature Voting instead. - Answers that are a number on a scale, like 1 to 5. Use a slider or a rating. ### Props - `question`: `ReactNode`. The question. It names the choices and the results for screen readers. - `description`: `ReactNode`. Optional details under the question, like when the poll closes. - `options`: `{ value: string; label: ReactNode; votes: number }[]`. The answers, in the order to show them. value must be unique. votes is the count so far. - `vote`: `string | null`. The option this person voted for, or null before they vote. Controlled. The poll shows the counts you pass as they are, plus a vote that is still saving. - `defaultVote`: `string`. An earlier vote by this person when you do not control vote. The poll shows results at once and does not count it again. - `onVote`: `(value: string) => void | Promise`. Called with the picked option when someone presses Vote. Return a promise, and the poll shows the vote at once with savingText until it settles. A rejection takes the vote back and shows errorText. When you control vote, set it and the counts only after the save succeeds, before your promise resolves. - `closed`: `boolean`. Default `false`. Voting has ended. Shows the final results with a Closed badge. - `disabled`: `boolean`. Default `false`. Blocks voting. The results are not affected. - `tone`: `"neutral" | "brand" | "danger" | "success" | "warning"`. Default `"neutral"`. Color of the picked choice, the Vote button, and the result bars. - `voteText`: `string`. Default `"Vote"`. The Vote button's text. - `yourVoteText`: `string`. Default `"Your vote"`. The badge on this person's choice in the results. - `savingText`: `string`. Default `"Saving…"`. The badge on this person's choice while the vote saves. yourVoteText takes its place once it saves. - `errorText`: `string`. Default `"Could not save your vote. Try again."`. Shown above the Vote button when a vote does not save. Screen readers announce it. - `closedText`: `string`. Default `"Closed"`. The badge on a closed poll. - `requiredText`: `string`. Default `"Pick an option to vote."`. Shown when someone presses Vote with nothing picked. Screen readers announce it. - `votesText`: `{ zero?: string; one?: string; two?: string; few?: string; many?: string; other: string }`. Default `{ one: "{count} vote", other: "{count} votes" }`. How a count of votes reads in each plural form, with {count} for the number. The poll picks the form with Intl.PluralRules for locale. Polish, for example, needs one, few, many, and other. - `locale`: `string`. Default `"en-US"`. A language tag for the counts, the percents, and the plural forms, like 'de-DE'. - `className`: `string`. Extra classes for the root. Later classes win, so className='gap-6' spaces the parts more. ### Accessibility - Open, the choices are a radio group named by the question. Arrow keys move between choices and pick, and Space picks. - Each radio is named by its label through aria-labelledby, so the name is in the server HTML too. - Picking does not vote, so arrowing through the choices is safe. Vote is a separate button. - Pressing Vote with nothing picked shows requiredText in a role="alert" message and moves focus to the first choice. - After someone votes here, focus moves to the results list, because the Vote button is gone. If the save fails, the choices come back and focus moves to the Vote button. Focus does not move if it is already somewhere else. - Results are a list named by the question. Each item reads its label, then 'Saving…' or 'Your vote' on this person's choice, then the count and the percent. The bars are hidden from screen readers. - A vote shows at once, so there is no spinner and no aria-busy. A failed save shows errorText in a role="alert" message, and the Vote button's aria-describedby points to it. - disabled takes the Vote button out of the tab order. The disabled choices stay in it, marked aria-disabled. - Bars use the tone fill, which the theme tests hold to 3:1 on the page and on cards. - Each bar sits on bg-track, which the theme tests hold to 1.25:1 on the page and on cards, so the full width shows. The track stays quiet, so a warning bar in light mode is only about 2.3:1 against it. The text carries every number. - Results grow in after a vote over --motion-duration-slow, and changed numbers fade in. data-motion="off" makes both instant. Reduced motion shows the bars at full width at once and drops the slide, but keeps the fade. - Every word has a prop with an English default: voteText, yourVoteText, savingText, errorText, closedText, requiredText, and votesText. locale formats the numbers and picks each plural form. ### Examples #### A poll that keeps its own state ```tsx ``` #### Save votes yourself ```tsx "use client"; import { useState } from "react"; const initial = [ { value: "mon", label: "Monday", votes: 12 }, { value: "wed", label: "Wednesday", votes: 6 }, { value: "fri", label: "Friday", votes: 2 }, ]; function PracticePoll() { const [options, setOptions] = useState(initial); const [vote, setVote] = useState(null); // The poll shows the vote at once, marked as saving. If this throws, it takes the vote back and says so. async function save(value: string) { // Replace this with your own request. fetch does not throw on a server error, so check ok. const response = await fetch("/api/planning-poll", { method: "POST", body: value }); if (!response.ok) throw new Error("The vote did not save."); // Set the vote and the counts only after the save succeeds. setOptions((all) => all.map((o) => (o.value === value ? { ...o, votes: o.votes + 1 } : o))); setVote(value); } return ( ); } ``` #### Final results ```tsx ``` #### In another language ```tsx ``` ## Choropleth Map > Regions shaded by value in one hue, in steps, with hatching for regions with no data, a legend that filters, and arrow keys that move from region to region. - Name: `choropleth-map` - Status: beta - Categories: charts - File: the install writes `choropleth-map.tsx` to your `ui` alias, `@/components/ui` by default. - Other registry items: `@txbrendan/chart`, `@txbrendan/skeleton`. The install adds them. - Gallery: https://txbrendan.dev/components/choropleth-map - Registry item: https://txbrendan.dev/r/choropleth-map.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/choropleth-map ``` ### Use it for - A value per country, state, or province, where where it is matters, like members by state or sales by country. - Pass shape, a map already projected: { width, height, regions: \[{ id, name, d, c }\] }, with a title or aria-label. - Pass values by region id, like { 'US-TX': 120 }. A region without a number is hatched and reads 'No data'. - Pass steps to set where each shade starts, like \[10, 50, 100\] for four shades. By default the shades split the values into quarters. - Pass onRegionSelect to make each region a button, and selected to outline the chosen one. - This site builds its shapes into /maps: world.json for countries, and admin1/\.json for each country's regions. Copy the ones you need into your app, or build your own in the same shape. ### Avoid it for - Exact numbers people must compare. Use BarChart or BreakdownList beside the map. - Values that only follow area or population. Show a rate, like per 1,000 people, so big regions do not win by size. - Streets, zooming, or panning. This map draws fixed shapes, not tiles. ### Props - `shape`: `ChoroplethShape`. The map, already projected: { width, height, regions, outline?, frames?, dots? }. Each region is { id, name, d, c, dot? }, where d is an SVG path and c a point inside it. - `values`: `Record`. Each region's value, by region id. - `steps`: `number[]`. Default `the quartiles of values`. Where each shade starts, lowest first. Three numbers make four shades. - `valueFormat`: `Intl.NumberFormatOptions`. How values read, in the readout and the legend, like { style: 'percent' }. - `selected`: `string | null`. The region outlined as chosen. - `onRegionSelect`: `(id: string) => void`. Called on click, Enter, or Space. Makes each region a button with aria-pressed. - `noDataText`: `string`. Default `"No data"`. What a region with no value reads. - `size`: `"sm" | "md" | "lg"`. Default `"md"`. Height. The map keeps its own shape inside it. - `loading`: `boolean`. Shows the regions as placeholders, or a placeholder box when there is no shape yet. - `error`: `ReactNode`. Shows this message in place of the map. Pass onRetry for a retry button. - `emptyText`: `ReactNode`. Default `"No regions to show"`. Shown when the shape has no regions. - `title`: `ReactNode`. Names the map. Pass this, aria-label, or aria-labelledby. - `locale`: `string`. Default `"en-US"`. The locale for numbers. The default keeps the server and the browser the same. - `className`: `string`. Extra classes for the figure. '\[--choropleth-color:var(--chart-3)\]' sets the hue. It defaults to --chart-1. ### Accessibility - The map is a group named by its title. Each region is named by its name and value, like 'Texas: 120'. - The map is one Tab stop. Arrow keys move to the nearest region that way, and Home and End go to the first and last by name. - With onRegionSelect, each region is a button with aria-pressed, and Enter or Space chooses it. - No data is a hatch, not only a lighter shade, so it reads apart from low values without color. - The legend steps are buttons. Hovering or focusing one shows only its regions. Pressing one keeps it on, with aria-pressed. - In forced colors, the shades become steps of the text color, the hatch stays, and the focused region is outlined in Highlight. ### Examples #### Members by state ```tsx import usa from "./maps/admin1/USA.json"; ``` #### Set steps and a format ```tsx ``` #### Choose a country ```tsx ``` ## Club Switcher > The club you're in, with its kit flag, name, and your roles, that opens a menu of every club you belong to. - Name: `club-switcher` - Status: beta - Categories: navigation - File: the install writes `club-switcher.tsx` to your `ui` alias, `@/components/ui` by default. - npm packages: `@base-ui/react`, `lucide-react`. The install adds them. - Other registry items: `@txbrendan/menu`, `@txbrendan/team-flag`. The install adds them. - Gallery: https://txbrendan.dev/components/club-switcher - Registry item: https://txbrendan.dev/r/club-switcher.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/club-switcher ``` ### Use it for - The top of an app's rail, for people in more than one club: a coach in one, a parent in another. - Give each club an id, its name, its kit colors for the TeamFlag, and your roles there, like "Coach · Admin". - Pressing it opens every club under it, with a check on the current one. Pass onJoin to end the menu with Join another club. - Pass value and onChange to control it, or defaultValue to start in a club. Without either it starts in the first. - Use inline to draw the open menu in a card or a doc, with no button. ### Avoid it for - Drawing a club's crest. Its kit colors stand in for it. Brand logos are never drawn. - Someone in one club only. Show the club's name and flag as plain text. - Switching teams inside one club. Use a select or tabs. ### Props - `clubs`: `{ id: string; name: string; colors?: [string, string]; pattern?: "hoops" | "halves" | "thirds" | "split"; role?: string }[]`. Required. Every club you belong to. colors are CSS colors from your data, set only on the flag's own style. - `value`: `string`. The club you're in. Controlled, with onChange. - `defaultValue`: `string`. The club you start in. Default the first. - `onChange`: `(id: string) => void`. Runs with the club's id when you switch. - `onJoin`: `() => void`. Offers "Join another club" at the end of the menu. - `inline`: `boolean`. Default `false`. Draws the open menu in the page's flow, with no button. Nothing closes it. - `className`: `string`. Extra classes on the button, or on the menu with inline. Later classes win. ### Accessibility - The button is named by the club and your roles, and says it opens a menu. - The menu opens with focus on your club. The arrow keys move without wrapping, Home and End go to the ends, letters jump to a club, Enter switches, and Esc closes it and puts focus back. - Each club is a menuitemradio, checked for the one you're in. The check is drawn, not only colored. - Inline, the menu is one Tab stop that lands on your club, with the same keys. Nothing closes it. - The kit flag is hidden from screen readers, since the name beside it says the club. ### Examples #### At the top of a rail ```tsx console.log("switch to", id)} onJoin={() => console.log("join")} /> ``` ## Code Field > One field for a code typed or pasted: a code sent by email or text, or a workspace's invite code. It drops anything else, and calls onComplete once the code is whole. - Name: `code-field` - Status: beta - Categories: forms - File: the install writes `code-field.tsx` to your `ui` alias, `@/components/ui` by default. - Other registry items: `@txbrendan/field-frame`, `@txbrendan/input`. The install adds them. - Gallery: https://txbrendan.dev/components/code-field - Registry item: https://txbrendan.dev/r/code-field.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/code-field ``` ### Use it for - A one-time code sent by email or text: characters="digits", six long by default. - A join code of letters and digits: characters="text". It shows in capitals. - Check the code in onComplete. It runs once the code is whole, so there is no Continue button to press. - Say where the code went and how long it works in hint, like "We sent it to riley@example.com. It works for 15 minutes." - Put a wrong or expired code in error, like "That code doesn't match". - Pass onResend to add a quiet "Send a new code" button after the hint or error. It reads "Sent" for 10 seconds after a press. ### Avoid it for - A row of one box per digit. One field takes a paste, autofill, and the phone's suggested code in one go. - A password or a PIN people choose. Use an input with type="password". - Long codes people copy from a page, like a licence key. Use an input. ### Props - `length`: `number`. Default `6`. How many characters make the code whole. - `characters`: `"digits" | "text"`. Default `"digits"`. Digits only, or letters and digits in capitals. Anything else is dropped, so a pasted "123 456" reads 123456. - `value`: `string`. The code. Use it with onValueChange. - `defaultValue`: `string`. The code at first render, when you do not control it. - `onValueChange`: `(code: string) => void`. Called with the cleaned code each time it changes. - `onComplete`: `(code: string) => void`. Called once the code reaches its length. Check it here. - `label`: `ReactNode`. Names the field, above it. - `hint`: `ReactNode`. Where the code went and how long it works. - `error`: `ReactNode`. A wrong or expired code. Replaces the hint, in red, and is announced. - `onResend`: `() => void`. Adds a "Send a new code" button after the hint or error. - `resendLabel`: `string`. Default `"Send a new code"`. The resend button's words. - `size`: `"sm" | "md" | "lg"`. Default `"md"`. Height, padding, and text size. The same heights as Input. - `disabled`: `boolean`. Default `false`. Blocks typing and the resend button. - `placeholder`: `string`. A sample code, like "TEAM26X". - `id`: `string`. The input's id. Defaults to a generated one. - `className`: `string`. Classes for the frame. Other props, like name and aria-\, land on the input. ### Accessibility - A native input named by its label, so typing, pasting, and autofill work as usual. - autocomplete="one-time-code" lets phones offer the code from the message they got. - Digits open the number keypad on phones. Text codes turn on capitals. - The hint or error describes the input. An error sets aria-invalid and is announced once when it appears. - The resend button keeps its width when it reads "Sent", and a polite live region says "Sent a new code". - On touch screens the text is 16px, so iOS Safari does not zoom in when the field gets focus. ### Examples #### A code sent by email ```tsx console.log("check", code)} onResend={() => console.log("resend")} /> ``` #### Letters and digits, seven long ```tsx ``` #### A wrong code ```tsx ``` ## Combobox > A text field that filters a list as you type, with groups, a check on the picked item, and chips for picking several. - Name: `combobox` - Status: beta - Categories: forms - File: the install writes `combobox.tsx` to your `ui` alias, `@/components/ui` by default. - npm packages: `@base-ui/react`. The install adds them. - Other registry items: `@txbrendan/chip-glide`, `@txbrendan/glide-highlight`, `@txbrendan/input`, `@txbrendan/tooltip`. The install adds them. - Gallery: https://txbrendan.dev/components/combobox - Registry item: https://txbrendan.dev/r/combobox.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/combobox ``` ### Use it for - Picking one item from a long list, where typing is faster than scrolling: a country, a time zone, a teammate. - One highlight glides from row to row as the pointer moves, and jumps when the arrow keys move it. Reduced motion makes it jump. - Picking several items from a long list. Set multiple, and each pick shows as a chip in the field. - Pass items as strings, as { value, label, disabled } objects, or as groups shaped { label, items }. - The value is the item's string value: a string, or a string array when multiple is set. It works uncontrolled with defaultValue, even from a server component. - Give the text field a name: aria-label, aria-labelledby, or an id that a label's htmlFor points at. - Set name to send the value with a form. Multiple sends one entry per pick. - The list opens at the end of the page body. In a box with its own theme, like a dark preview on a light page, pass that box as container so the list keeps its colors. A container that clips its overflow can clip the list. ### Avoid it for - Fewer than about 7 items. Use a select or a radio group, so people see every choice at once. - Free text, like a search box with suggestions. A combobox only accepts items from its list. - Running commands or jumping to pages. Use a menu or links instead. - Object values. Map each record to { value: id, label: name }, then look the record up by its id. ### Props - `items`: `(string | { value: string; label: string; disabled?: boolean })[] | { label: string; items: ... }[]`. The choices. A string is both value and label. Groups show their label above their items. - `multiple`: `boolean`. Default `false`. Pick any number of items. The value becomes a string array, and picks show as chips. - `defaultValue`: `string | null | string[]`. The picked value at first render, when you do not control it. A string array when multiple is set. - `value`: `string | null | string[]`. Controlled value. Use it with onValueChange. - `onValueChange`: `(value: string | null | string[], details) => void`. Called with the new value on each pick. Deleting the text sets a single value to null. - `aria-label`: `string`. Names the text field. TypeScript requires this, aria-labelledby, or id. - `id`: `string`. The text field's id, for a label's htmlFor. - `placeholder`: `string`. Hint text in the empty field. Hidden once a chip is in the field. - `emptyText`: `ReactNode`. Default `"No results found."`. Shown in the list when nothing matches. Screen readers announce it. - `size`: `"sm" | "md" | "lg"`. Default `"md"`. Field height, padding, and text size. The same heights as Input. Density scales them. - `disabled`: `boolean`. Default `false`. Blocks typing and picking, and removes the field from the tab order. - `readOnly`: `boolean`. Default `false`. Shows the value and the list but blocks changes. - `required`: `boolean`. Default `false`. The form will not submit until something is picked. - `name`: `string`. Form field name. The picked value is sent with the form. - `aria-invalid`: `boolean`. Shows the danger border. Set it when validation fails, and link the message with aria-describedby. - `filter`: `((item, query: string) => boolean) | null`. Decides which items match the text. The default matches labels, ignoring case and accents. Pass null when a server filters. - `inputValue`: `string`. Controlled text. Use it with onInputValueChange, for example to search a server. - `onInputValueChange`: `(inputValue: string) => void`. Called as the text changes, with the new text. - `open`: `boolean`. Controlled open state. Use it with onOpenChange. - `onOpenChange`: `(open: boolean) => void`. Called when the list opens or closes. - `container`: `HTMLElement | ShadowRoot | RefObject | null`. Where the list opens. By default, at the end of the page body, so no parent can clip it. Pass an element, or a ref itself (not ref.current), to open it inside, for example to keep a parent's theme. While it is null, the list waits and does not open. Only client code has elements and refs. - `effect`: `"rise" | "grow"`. Default `"rise"`. How the list opens and closes. rise fades in and moves out from the field. grow fades in and grows from the field, and closes the same way. Left out, it follows an effect-\ class on \, where popups open, and rises with none. - `className`: `string`. Classes for the field. Later classes win, so className='max-w-60' sets the width. ### Accessibility - The text field has role="combobox". The list is a listbox, and each item is an option with aria-selected. - Focus stays in the text field. aria-activedescendant tells screen readers which item is highlighted. - Down Arrow opens the list on the first item. Up and Down Arrow move, Enter picks, and Escape closes. Typing filters. - TypeScript requires aria-label, aria-labelledby, or an id. A label's htmlFor can name the field. - The check mark is hidden from screen readers. aria-selected says which items are picked. - The empty text is a polite live region, so screen readers hear when nothing matches. - Group labels name their groups through aria-labelledby. - With multiple, Left Arrow at the start of the text moves to the chips. Backspace or Delete removes the focused chip, and Backspace in empty text removes the last one. - The open button is out of the tab order, so Tab moves on to the next control. Clicking anywhere in the field opens the list. - The field shows the --ring outline while the text field inside has focus. The theme tests hold --ring to 3:1. - Highlighted items use the accent pair, and group labels and empty text use muted text on the popover. The theme tests hold both to 4.5:1. - The list fades in and slides by --motion-distance. It closes with a quicker fade and a slight shrink toward the field. Reduced motion keeps the fades and drops the slide and the shrink. - The open button's label, 'Show options', and the chips' 'Remove …' labels are English. Edit the file to translate them. ### Examples #### Pick one item ```tsx ``` #### With a label, a value, and a form name (needs @txbrendan/label) ```tsx import { Label } from "@/components/ui/label";
Country
``` #### Groups ```tsx ``` #### Pick several, shown as chips ```tsx ``` #### Controlled ```tsx "use client"; import { useState } from "react"; const people = [ { value: "u1", label: "Ada Lovelace" }, { value: "u2", label: "Grace Hopper" }, ]; function AssigneePicker() { const [assignee, setAssignee] = useState(null); return ; } ``` #### Grows from the field ```tsx ``` ## Command Menu > Search everything from anywhere: ⌘K opens it over the page, results come grouped, and the arrows and Enter pick one. - Name: `command-menu` - Status: beta - Categories: navigation - File: the install writes `command-menu.tsx` to your `ui` alias, `@/components/ui` by default. - npm packages: `@base-ui/react`. The install adds them. - Other registry items: `@txbrendan/action-keys`. The install adds them. - Gallery: https://txbrendan.dev/components/command-menu - Registry item: https://txbrendan.dev/r/command-menu.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/command-menu ``` ### Use it for - One per app, to jump to people, teams, events, pages, and actions from anywhere. - Keep open in state. Set it in onOpen, which ⌘K (Ctrl+K) calls, and clear it in onClose. - Put a Search button on screen that opens it too. Teach ⌘K in that button's tooltip, never in the layout. - Give each item a group, like "People" or "Actions". Groups show in the order they first appear, five results each. - Mark a few items recent. They show before anything is typed. - Use inline to show it open in a card or a docs page. ### Avoid it for - Picking a value for a form. Use Combobox, which keeps the choice in the field. - A short list of actions on one thing. Use Menu. - Two command menus on one page with shortcut on. Only one should listen for ⌘K. ### Props - `items`: `CommandItem[]`. The results: { id, person?, avatar?, label?, icon?, group?, meta?, keywords?, recent?, onSelect? }. A person has a name and an avatar element. Anything else has a label and an icon element. - `open`: `boolean`. Default `false`. Whether it is open over the page. Not used with inline. - `onOpen`: `() => void`. ⌘K (Ctrl+K) was pressed while it was closed. - `onClose`: `() => void`. Esc, a press outside, ⌘K, or a choice closed it. - `onSelect`: `(item: CommandItem) => void`. Runs after a result is chosen. It closes first, then the item's own onSelect runs, then this. - `placeholder`: `string`. Default `"Search people, teams, and pages"`. The field's placeholder. - `label`: `string`. Default `"Search"`. Names the dialog and the field for screen readers. - `shortcut`: `boolean`. Default `true`. Listen for ⌘K on the page. A rich text editor keeps ⌘K for its links. - `inline`: `boolean`. Default `false`. Open in the page with no scrim. Choosing a result or Esc clears the words. - `effect`: `"rise" | "grow"`. Default `"rise"`. How the menu and its backdrop open and close. rise fades in and drops into place. grow fades in and grows in place, and closes the same way. Left out, it follows an effect-\ class on \, where popups open, and rises with none. Not used with inline. - `className`: `string`. Extra classes on the menu. Later classes win. ### Accessibility - It is a modal dialog named by label. Focus goes to the field, Tab stays inside even when pressed fast, and the page behind is inert. - When it closes, focus goes back to what opened it. - The field is a combobox. The arrows move the highlight and Enter chooses. Focus stays in the field. - Esc clears typed words first. The next Esc closes it. - Results are grouped under their group's name, which screen readers hear. - Avatars and icons are hidden from screen readers, since the name says who or what it is. ### Examples #### Open it with ⌘K or a button ```tsx "use client"; import { useState } from "react"; import { useRouter } from "next/navigation"; const ITEMS = [ { id: "sam", person: "Sam Carter", group: "People", meta: "Design lead, Mobile app", recent: true }, { id: "design", label: "Design", group: "Teams" }, { id: "fees", label: "Fees", group: "Pages" }, ]; export function Search() { const [open, setOpen] = useState(false); const router = useRouter(); return ( <> setOpen(true)} onClose={() => setOpen(false)} onSelect={(item) => router.push(`/${item.id}`)} /> ); } ``` #### Open in the page ```tsx ``` #### Grows in place ```tsx "use client"; import { useState } from "react"; const ITEMS = [ { id: "design", label: "Design", group: "Teams" }, { id: "fees", label: "Fees", group: "Pages" }, ]; export function Search() { const [open, setOpen] = useState(false); return ( <> setOpen(true)} onClose={() => setOpen(false)} effect="grow" /> ); } ``` ## Composer > A message to people, written and sent in place, with who it reaches above it and Undo for 8 seconds after Send. - Name: `composer` - Status: beta - Categories: ai, forms - File: the install writes `composer.tsx` to your `ui` alias, `@/components/ui` by default. - Other registry items: `@txbrendan/motion`, `@txbrendan/audience`, `@txbrendan/button`, `@txbrendan/icon`, `@txbrendan/kbd`, `@txbrendan/menu`, `@txbrendan/peek-card`, `@txbrendan/textarea`, `@txbrendan/tool-button`, `@txbrendan/tooltip`. The install adds them. - Gallery: https://txbrendan.dev/components/composer - Registry item: https://txbrendan.dev/r/composer.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/composer ``` ### Use it for - Writing to a team, a group, or one person, under their thread. - Pass everyone in to, as for Audience. Juniors go by juniorMessages. - Show the message in its thread from onSend. Take it out in onUndo. Deliver it in onCommit, when the 8 seconds end. - Pass later with times to offer Send later, like Mon 08:00. ### Avoid it for - An announcement in a sheet. Put Audience above a Textarea there, and make Send the sheet's main action. - A one-line reply to a comment. Use Inline Reply. - Long, formatted writing. Use Editor. ### Props - `to`: `Recipient[]`. Required. Who the message is for. See Audience. - `toLabel`: `string`. What the group is called, like Art class. It titles the count's peek and fills the placeholder. - `juniorMessages`: `"guardians" | "copy"`. Default `"guardians"`. Where messages to juniors go: to their parents instead, or to the junior with their parents copied. - `placeholder`: `string`. Default `"Write to {toLabel}"`. The field's placeholder. - `defaultValue`: `string`. Words to start with, like a draft. - `later`: `{ id: string; label: string; at: string | Date }[]`. Times to offer under Send later. Without it, there is only Send. - `sendLabel`: `string`. Default `"Send"`. Send's words. - `onSend`: `(message: { text: string; at: string | Date | null; reach: AudienceReach }) => void`. Pressed: show the message where it lands. at is null for now, or the chosen later time. - `onUndo`: `(message) => void`. Taken back: take it out of the thread. The words are back in the field. The same object onSend got. - `onCommit`: `(message) => void | Promise`. Final: deliver it now. Return a promise, and a failure turns the button into Retry. - `onAddGuardian`: `(junior: { person: string; photo?: string }) => void`. The fix for a junior with no parent on file. See Audience. - `size`: `"sm" | "md" | "lg"`. Default `"md"`. Text, field, and button size. - `disabled`: `boolean`. Default `false`. Turns the field and the buttons off. - `className`: `string`. Extra classes on the root. Later classes win. ### Accessibility - The field is named Message to {toLabel}, and Audience's line describes it, so people hear who it goes to. - ⌘Enter or Ctrl+Enter sends from the field. Send's tooltip teaches it, and Send has aria-keyshortcuts. - Send says what happened in its name: Sent to 3, then Sent to 3. Press to undo. The page's live region says it once. - Undo arms a moment after a key press, or when the pointer leaves after a click, so a double press never undoes. - In the empty field, ⌘Z takes back the message that just went and puts the words back. Anywhere else, ⌘Z does what the page's ⌘Z does. - Send later is a menu button. Once a time is chosen, it says when, and a press on it undoes. ### Examples #### To a group, with Send later ```tsx setThread((all) => [...all, message])} onUndo={(message) => setThread((all) => all.filter((m) => m !== message))} onCommit={(message) => deliver(message)} /> ``` #### To one person ```tsx ``` ## Consensus Meter > How a group of raters lean, one segment per rating, and where their low, average, and high targets sit against the current value. - Name: `consensus-meter` - Status: beta - Categories: charts - File: the install writes `consensus-meter.tsx` to your `ui` alias, `@/components/ui` by default. - Other registry items: `@txbrendan/badge`, `@txbrendan/morph-label`, `@txbrendan/motion-timing`, `@txbrendan/rolling-number`, `@txbrendan/skeleton`. The install adds them. - Gallery: https://txbrendan.dev/components/consensus-meter - Registry item: https://txbrendan.dev/r/consensus-meter.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/consensus-meter ``` ### Use it for - Showing how analysts or reviewers lean, and where their price or score targets sit against today's value. - Pass counts for the negative, neutral, and positive sides. Pass targets to add the track of low, average, and high. - Pass verdict for the overall call. It turns green or red when most ratings lean one way. - Change counts or targets, as from tabs, and the counts roll, the segments grow, shrink, and change color in place, the marks glide, and each label glides to its new column. - Pass noun, like { one: "analyst", other: "analysts" }, for the count. ### Avoid it for - A rating out of five stars or a single score. Use Progress or a plain number. - More than three sides. The split has negative, neutral, and positive only. - Values over time. Use LineChart. ### Props - `counts`: `{ negative: number; neutral: number; positive: number }`. How many ratings fall on each side. Up to 40 draw one segment each. More draw one segment per side, sized by its share. Counts below 0 count as 0, and parts round to whole ratings. - `targets`: `{ low: number; average: number; high: number; current: number }`. The targets and the current value. The track always fits the current value, even outside the targets. A low above the high is read the other way round. - `verdict`: `ReactNode`. The overall call, shown in a badge. Green when 60% or more lean positive, red when 60% or more lean negative. Its words morph when they change, and long words are cut short. - `aria-label`: `string`. Names the meter. TypeScript requires aria-label or aria-labelledby. - `valueFormat`: `Intl.NumberFormatOptions`. Default `US dollars, with cents on every target when any has them, and short form like $2.35M from $100,000 up`. Formats the targets. - `locale`: `string`. Default `"en-US"`. The locale for numbers. Fixed, so server and browser print the same text. - `labels`: `{ negative?, neutral?, positive?, low?, average?, current?, high?: string }`. Default `Bearish, Neutral, Bullish, Low, Average, Current, High`. The words for each side and each target. - `noun`: `{ one: string; other: string }`. Default `{ one: "rating", other: "ratings" }`. What one rating is called, for the count. - `loading`: `boolean`. Default `false`. Shows placeholders at the same size. - `emptyText`: `ReactNode`. Default `"No ratings yet"`. Shown when every count is 0. - `className`: `string`. Extra classes. Later classes win. ### Accessibility - Renders a \
named by aria-label or aria-labelledby. TypeScript requires one. - Every count and every target is printed as text, so nothing lives only in color. The segments and the track are hidden from screen readers, and a hidden line reads each target and how far it sits from the current value, which sighted people see on hover or tap. - Each side's color sits beside its word: Bearish, Neutral, Bullish. The targets differ by shape: plain dots for the ends, rings for the average and the current value. The average and the line to it take the color of the lean, up or down. With forced colors, the bar, track, and marks take system colors, so they stay visible. - Hovering a side lifts its segments and fades the others. Hovering a target grows its mark, fades the others, and swaps its word for how far it sits from the current value. On touch, a tap does the same, and a tap anywhere but on a part lets go. Each side has a strip 26px tall over the thin bar, and each mark a 24px target. - Once on screen, the bar fills from the start and each target glides out from the current value. When the data changes, counts roll, segments resize, and marks and labels glide. With motion off, it all shows at once. Right to left, the labels and the track both run from the right. - Loading and the empty text are read out through a status line that stays on the page. ### Examples #### Ratings and targets ```tsx ``` #### The split alone ```tsx ``` #### While it loads ```tsx ``` ## Context Window > A meter for how much of a model's context window is used, like 84K of 200K tokens. It splits the use into parts with a legend, and turns warning near the limit. - Name: `context-window` - Status: beta - Categories: ai, display - File: the install writes `context-window.tsx` to your `ui` alias, `@/components/ui` by default. - Other registry items: `@txbrendan/badge`, `@txbrendan/button`, `@txbrendan/card`, `@txbrendan/notice`, `@txbrendan/skeleton`. The install adds them. - Gallery: https://txbrendan.dev/components/context-window - Registry item: https://txbrendan.dev/r/context-window.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/context-window ``` ### Use it for - Show what fills a model's context in a chat or agent product, beside the composer or in a session panel. - Pass limit, the window's size in tokens, and parts in the order the bar shows them, like system prompt, tools, files, and chat. - Keep to five parts. Each takes the next chart color. Group small ones into Other. - It turns warning at 80% of the limit and danger once full. Pass warnAt to warn earlier, like 0.6. - Pass action for the next step near the limit, like a Compact chat or New chat button. - Give a part its own action to free up room, like { label: "Remove" } on a file or { label: "Compact", loading } on the chat. Pass the parts again with the new tokens, and the bar moves. - Pass legend={false} and size="sm" for a small space. ### Avoid it for - A task that runs, like an upload. Use Progress. - One plain share with no parts, like 72% of storage. Use Progress or Ring Progress. - Billing or usage over a month, compared side by side. Use Breakdown List. ### Props - `parts`: `{ id?: string; label: string; tokens: number; action?: ContextWindowPartAction }[]`. Required. What fills the window, in the order the bar shows them. Five at most. - `ContextWindowPartAction`: `{ label: string; onClick?: () => void; loading?: boolean; disabled?: boolean }`. Type. A quiet button at the end of the part's legend row. Pass functions from a client component. - `limit`: `number`. Required. The window's size in tokens, like 200000. - `title`: `ReactNode`. Default `"Context window"`. The card's title. It names the meter. - `model`: `ReactNode`. A small tag beside the title, like the model's name. - `warnAt`: `number`. Default `0.8`. The share of the limit, from 0 to 1, where it turns warning. It turns danger once full. - `tone`: `"neutral" | "brand" | "danger" | "success" | "warning"`. Default `"neutral"`. Colors the percent and the last line. Left out, it is neutral, then warning from warnAt, then danger once full. Passed, it stays that tone. - `legend`: `boolean`. Default `true`. Shows each part's name, tokens, and action under the bar. - `action`: `ReactNode`. A button in the last row, like Compact chat or New chat. - `loading`: `boolean`. Default `false`. Shows placeholders while the numbers load. - `size`: `"sm" | "md"`. Default `"md"`. Bar height and the number's size. - `locale`: `string`. Default `"en-US"`. Formats the numbers the short way, like 84K. - `className`: `string`. Classes for the card. Later classes win. ### Accessibility - The card is a group named by the title. The bar is a meter with the same name, and reads like "84K of 200K tokens used, 42%". - The bar's colored parts are hidden from screen readers. The legend says each part's name and tokens in text. - A part's action is named with the part, like "Remove Files", so each button says what it acts on. - Near the limit, the last line says Almost full or Full in words, so the warning does not rest on color alone. - In forced-colors mode the bar draws a border and its parts fill with the text color. ### Examples #### Split by part, under the limit ```tsx ``` #### Near the limit, with a next step ```tsx import { Button } from "@/components/ui/button"; import { ContextWindow } from "@/components/ui/context-window"; export function SessionMeter() { return ( Compact chat } /> ); } ``` ## Data Table > A dense table on Table: sortable columns, people through Person, statuses, peeks, your row, zones, breaks, and quick actions per row. - Name: `data-table` - Status: beta - Categories: data, display - File: the install writes `data-table.tsx` to your `ui` alias, `@/components/ui` by default. - Other registry items: `@txbrendan/motion`, `@txbrendan/hover-card`, `@txbrendan/hover-actions`, `@txbrendan/motion-timing`, `@txbrendan/peek-card`, `@txbrendan/person`, `@txbrendan/row-actions`, `@txbrendan/skeleton`, `@txbrendan/status-text`, `@txbrendan/table`. The install adds them. - Gallery: https://txbrendan.dev/components/data-table - Registry item: https://txbrendan.dev/r/data-table.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/data-table ``` ### Use it for - Rows of records read across: a team, payments, attendance. Put it in a Card with className="px-0" on the part that holds it, so it runs edge to edge. - It is generic over the row: every callback sees your row type. Keep columns stable, outside the component or in useMemo, so a sort is not redone each render. - A field shaped { person, photo } draws as Person. Use render for anything else. - status puts the row's status right after a cell's value, usually the name. A table's status follows the name, never its own column. - peek explains a value: who, when, why. Plain text gets a dotted underline. - sortable adds a header button. The first press sorts text A to Z and numbers high to low, and the next press flips it. aria-sort says which. - highlight marks your rows with a You tag and their own wash. zones tint a run of rows, like the top places, with a 2px rule where it meets the rest. breaks add a labeled line, like Your place. - rowActions spring in over the row's end on hover or focus, and their keys work then. If they would cover a peek or a status, the table keeps a band at the end for them. - hideBelow drops a column while the table is narrow, so the names keep their room. ### Avoid it for - A list of things that are not read across. Use ListRow. - Sorting a table with zones or breaks. They follow row positions, so a sort moves them onto other rows. - A column for the status. Put status on the name column. - Colors alone for a zone. Say what it means in a peek or in words. ### Props - `columns`: `DataColumn[]`. Required. Each: { key, label, short?, width?, align?, numeric?, render?(row, hovered), peek?(row), underline?, status?(row), rowHeader?, sortable?, sortValue?(row), hideBelow?, className? }. short shows in place of label, like "P" for Played, while label is read. - `rows`: `Row[]`. Required. Long tables draw 100 rows at a time as the reader nears the end. - `rowKey`: `string | ((row, index) => string | number)`. A stable key per row. Default row.id, then the position. - `breaks`: `{ after: number; label: string; tone?; side?: "above" | "below" }[]`. A labeled line after a row index. Its arrow says whether the label is about the rows above or below. - `zones`: `{ from: number; to: number; tone? }[]`. Runs of row indices tinted in a tone as one band, with a 2px rule where the band meets the rest. - `highlight`: `(row) => boolean`. Rows that are yours: a You tag after the name and their own wash, or the tag alone inside a zone. - `highlightLabel`: `string`. Default `"You"`. The tag on a highlighted row, which screen readers hear before its name. - `rowActions`: `(row) => HoverAction[]`. Quick actions over the row's end while it is hovered or holds focus. - `onRowClick`: `(row) => void`. Makes each row one press, named by its row header. - `sort`: `{ key: string; direction: "ascending" | "descending" } | null`. Controlled sort. - `defaultSort`: `{ key: string; direction: "ascending" | "descending" } | null`. The first sort, uncontrolled. - `onSortChange`: `(sort) => void`. Hears each sort a header button asks for. - `caption`: `ReactNode`. Names the table, under it. - `aria-label`: `string`. Names the table when it has no caption. - `loading`: `boolean`. Default `false`. Holds the space with three placeholder rows. - `empty`: `ReactNode`. Default `"Nothing here yet"`. What shows with no rows. - `data-slot`: `string`. Default `"data-table"`. The root's slot, for a part built on DataTable, like Leaderboard. - `className`: `string`. Extra classes on the wrapper. Set --data-table-edge to change the first and last columns' inset. Later classes win. ### Accessibility - A real \, with column headers. A column marked rowHeader is a \
, so each cell is read with the row's name. - A sortable header is a button inside the \ . The sorted header carries aria-sort, ascending or descending. - With onRowClick, each row's press is one real button named by its row header. Its focus ring goes around the whole row. Controls in the row keep their own presses, and none sits inside another. - A highlighted row's row header starts with "You," for screen readers, so every cell is read with it. Its tag is words, so it stays in forced colors. - A zone's edges are 2px borders, so they stay in forced colors. Its meaning needs words, like a peek on its rows. - Row actions show on hover and on focus inside the row. Their single-key shortcuts work only while the row is lit. - Each row carries data-peek-row, so a peek opens beside it, and ↑↓ step between peeks. - While loading, the table is aria-busy. ### Examples #### Sortable columns with people ```tsx type Member = { id: string; name: { person: string }; role: string; projects: number }; const columns: DataColumn[] = [ { key: "name", label: "Name", rowHeader: true, sortable: true, sortValue: (row) => row.name.person }, { key: "role", label: "Role" }, { key: "projects", label: "Projects", numeric: true, sortable: true }, ]; ``` ## Date Picker > A field that shows a day, like "Sat 3 Oct", and opens a calendar under it to pick one. Weeks start on Monday, and the year shows only when it is not this year. - Name: `date-picker` - Status: beta - Categories: dates, forms - File: the install writes `date-picker.tsx` to your `ui` alias, `@/components/ui` by default. - Other registry items: `@txbrendan/calendar`, `@txbrendan/field-frame`, `@txbrendan/popover`. The install adds them. - Gallery: https://txbrendan.dev/components/date-picker - Registry item: https://txbrendan.dev/r/date-picker.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/date-picker ``` ### Use it for - One day for something people plan: a meeting, a workshop, an invoice's due date. - Give it a label, like "Event date". Without one, pass aria-label. - The value is a day as "YYYY-MM-DD", with no time and no time zone. - Set min and max for the days people may pick, and disabledDates for days that are taken. - Put what is wrong in error, like "Pick a day from today on." It replaces the hint and is said once. - Pass name to send the day with a form. ### Avoid it for - A start and an end day. Use a Calendar with mode="range". - A calendar that stays on the page, like a schedule. Use a Calendar. - A birth date or another day far in the past. Typing it is quicker than paging back through months. ### Props - `label`: `ReactNode`. Names the field, above it. Pressing it focuses the button and does not open the calendar. - `value`: `string | null`. The picked day, "YYYY-MM-DD". Use it with onValueChange. - `defaultValue`: `string | null`. The picked day at first render, when you do not control it. - `onValueChange`: `(day: string) => void`. Called with the new day when someone picks one. - `placeholder`: `string`. Default `"Pick a date"`. Shown while no day is picked. - `hint`: `ReactNode`. A short note under the field. - `error`: `ReactNode`. Replaces the hint, in red, and is announced once. - `min`: `string`. The earliest day people can pick, "YYYY-MM-DD". - `max`: `string`. The latest day people can pick, "YYYY-MM-DD". - `disabledDates`: `string[] | (date: string) => boolean`. Days people cannot pick. - `weekStartsOn`: `0 | 1 | 2 | 3 | 4 | 5 | 6`. Default `1`. The first column. 1 is Monday. - `locale`: `string`. Default `"en-GB"`. A language tag for the button and the calendar. - `size`: `"sm" | "md" | "lg"`. Default `"md"`. Height and text size of the button, the label, and the calendar. - `disabled`: `boolean`. Default `false`. Blocks the button. - `name`: `string`. Form field name. Sends the day, or nothing while none is picked. - `aria-label`: `string`. Names the field when there is no visible label. - `className`: `string`. Classes for the frame. Later classes win. ### Accessibility - The button's name is the label and then the day, like "Event date, Sat 3 Oct". It says it opens a dialog, and whether it is open. - The calendar opens with focus on the picked day, or today, or the month's first day. - In the calendar the arrows move a day or a week, Home and End go to the week's ends, and Page Up and Page Down move a month, with Shift a year. - Enter, Space, or a click picks a day. That closes the calendar and puts focus back on the button. - Escape or a click outside closes it without a change. - The hint or the error describes the button. The error is announced once when it appears. ### Examples #### With a picked day and a hint ```tsx ``` #### Limits and taken days ```tsx ``` ## Dialog > A window over the page, with a backdrop, for a choice or a short task that must be done or cancelled before going on. - Name: `dialog` - Status: beta - Categories: overlays - File: the install writes `dialog.tsx` to your `ui` alias, `@/components/ui` by default. - npm packages: `@base-ui/react`, `class-variance-authority`. The install adds them. - Other registry items: `@txbrendan/action-keys`. The install adds them. - Gallery: https://txbrendan.dev/components/dialog - Registry item: https://txbrendan.dev/r/dialog.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/dialog ``` ### Use it for - A choice people must make before they go on, like confirming a delete. - A short form that needs full attention, like editing a profile. - Always give it a DialogTitle. It names the dialog for screen readers. - Put the actions in DialogFooter, with the safe choice before the main action, which goes last. - An extra quiet action, like Discard, goes first as a Button with emphasis="ghost". It sits at the start of the row, away from the main action. - The dialog opens at the end of the page body. In a box with its own theme, like a dark preview on a light page, pass that box as container on DialogPopup so the dialog and its backdrop keep the box's colors. ### Avoid it for - Extra details or a quick edit beside a button. Use a popover, which does not block the page. - A message that needs no answer. Use an alert on the page. - Long forms or many steps. Use a page. - Opening a dialog when the page loads. People did not ask for it. - More than three actions, or long labels, in DialogFooter. It stays on one row, so on a phone the dialog would scroll sideways. - closeButton={false} when the footer starts with Discard or Delete and no field comes before it. Focus would start on that button, so Enter would run it. ### Props - `Dialog`: `{ open?: boolean; defaultOpen?: boolean; onOpenChange?: (open: boolean, details) => void; disablePointerDismissal?: boolean }`. Root. Holds the open state and renders no element. Takes open, defaultOpen, onOpenChange, and disablePointerDismissal. - `open`: `boolean`. Dialog. Whether it is open, controlled. Use it with onOpenChange. - `defaultOpen`: `boolean`. Default `false`. Dialog. Whether it is open at the start, when you do not control it. - `onOpenChange`: `(open: boolean, details) => void`. Dialog. Called with the new open state when it opens or closes. - `disablePointerDismissal`: `boolean`. Default `false`. Dialog. Keeps a press outside from closing it. Esc and the Close button still close it. - `DialogTrigger`: `ComponentProps<"button"> & { render?: ReactElement }`. Part. The button that opens it. Pass render={\ ); } ``` #### Wider, for a table or a long form (needs @txbrendan/button) ```tsx import { Button } from "@/components/ui/button"; }>Import contacts Import contacts Check each row before you import it. ``` #### Grows in place (needs @txbrendan/button) ```tsx import { Button } from "@/components/ui/button"; }>Rename Rename file The new name shows for everyone with access. ``` ## Dither Icon > 60 original monochrome icons with optional shifting dither dots, transparent backgrounds, and theme colors. - Name: `dither-icon` - Status: beta - Categories: media, display - File: the install writes `dither-icon.tsx` to your `ui` alias, `@/components/ui` by default. - Other registry items: `@txbrendan/dither`. The install adds them. - Gallery: https://txbrendan.dev/components/dither-icon - Registry item: https://txbrendan.dev/r/dither-icon.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/dither-icon ``` ### Use it for - Illustrated navigation, empty states, and retro interfaces. - Use ditherIconNames to list all 60 icons, covering everyday controls, files, devices, objects, and nature. - Use animated to swap interior dots while outlines, detail lines, and the ink count in each tile stay fixed. Thin solid strokes stay still. - Provide a pause control for looping decorative animation. Use paused on one icon, or set --dither-icon-play-state: paused on a container to freeze a collection. - Use 32, 64, or 96px to keep the 32-pixel grid sharp. - getDitherIconSvg(name, fill) returns a still standalone SVG; fill accepts a hex color or defaults to currentColor. Inline SVG inherits text color; a downloaded file uses the viewer's default ink. ### Avoid it for - Small toolbar actions below 32px: use Icon or Solid Icon instead. - Using texture or color alone to communicate status. Add a visible label. ### Props - `texture`: `"flat" | "dither" | "gradient" | "grain"`. dither draws the shape as dots, denser toward the bottom right, gradient as color that deepens the same way, and grain as still specks over a light wash. Hover fills each in to the solid shape, and shows a flat icon's dots. Left out, the icon follows the Texture around it, and is flat with none. - `animated`: `boolean`. Default `false`. Dithered, loops four crisp dot patterns on the theme's pulse duration. No translation, scaling, or fading. - `paused`: `boolean`. Default `false`. Freeze on the current animation frame. Has no effect on a still icon. - `fill`: `string`. Optional SVG artwork fill. Use a chosen hex color to override the tone. - `name`: `DitherIconName`. Default `"folder"`. One of the 60 names in ditherIconNames. - `size`: `"sm" | "md" | "lg"`. Default `"md"`. 32, 64, or 96 pixels. - `tone`: `"neutral" | "brand" | "danger" | "success" | "warning"`. Default `"neutral"`. The theme color used for every ink pixel. - `title`: `string`. Accessible name for a standalone icon. Omit beside equivalent text. - `className`: `string`. Classes merged last on the SVG. ### Accessibility - Decorative icons are hidden from screen readers. A title makes the SVG a named image. - The SVG does not take keyboard focus. Icon-only actions need their own accessible label. - Reduced motion and the theme's Motion Off setting show the first frame without animating. Animation does not announce individual frames. - Dithered shading is decorative; it is not a contrast guarantee. ### Examples #### Animated texture ```tsx ``` #### With a label ```tsx
Project files
``` #### Standalone image ```tsx ``` ## Dither Motion > Moves a chart's dithered dots: an intro, a loop at rest, and dots that fill in near the pointer. It draws on a canvas under the chart. - Name: `dither-motion` - Status: beta - Categories: motion, display - File: the install writes `dither-motion.tsx` to your `ui` alias, `@/components/ui` by default. - Other registry items: `@txbrendan/dither`, `@txbrendan/motion-timing`. The install adds them. - Gallery: https://txbrendan.dev/components/dither-motion - Registry item: https://txbrendan.dev/r/dither-motion.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/dither-motion ``` ### Use it for - A chart whose dithered areas should move. Put a canvas under its SVG, the same size, and pass both with the areas' paths and colors. - Load it with import() on first hover or focus, or once the chart is on screen. The dots at rest are the SVG mask, so nothing waits on it. - The same box the chart passes to DitherBoxMask, so the canvas and the mask draw the same dots. A chart with a mask per bar passes each bar's box as boxes, and the same thin. ### Avoid it for - Dots that never move. DitherBoxMask draws them with no script. - Shapes other than filled areas. Lines and labels stay in the SVG, on top. ### Props - `startDitherMotion`: `(options: DitherMotionOptions) => DitherMotion`. Helper. Sets up moving dots for one chart and returns intro, idle, point, and stop. Options: host, the chart's root; canvas; width and height, the SVG's size in CSS pixels; box; boxes, one per bar, each laying out its own dots; fill; start; thin; and shapes, each { d, paint, top?, bottom?, fade? }, bottom area first. Nothing draws until one of them asks. - `intro`: `(style: "sweep" | "rain" | "ripple" | "pop" | "fall") => Promise`. Plays an intro over the motion pulse time. It resolves when the last dot is in, or at once when motion is off. - `idle`: `(style: "none" | "wave" | "twinkle" | "breathe" | "drift") => void`. A loop at rest. Wave passes a band of extra dots across, then rests. Twinkle blinks single dots out and on, each on its own clock. Breathe fills the thin edge in deeper and back. Drift moves soft patches of extra dots slowly across. It stops while the chart is off screen. - `point`: `(x: number | null, y?: number) => void`. Fills in hidden dots within 56px of the pointer, in the SVG's pixels. Pass null when the pointer leaves, and they fade back. - `stop`: `() => void`. Stops every motion, clears the canvas, and hands the dots back to the mask. Call it on unmount. ### Accessibility - Motion off and reduced motion set the pulse to 0, and then nothing moves. The mask keeps drawing the dots at rest. - Forced colors and texture flat move nothing either, since the chart draws no dots then. - The canvas is aria-hidden. The chart's SVG keeps its name, and the dots carry no meaning of their own. ### Examples #### Play an intro on a dithered area ```tsx import { useEffect, useRef } from "react"; function MovingArea({ d, box }: { d: string; box: DitherBox }) { const host = useRef(null); const canvas = useRef(null); useEffect(() => { if (!host.current || !canvas.current) return; const motion = startDitherMotion({ host: host.current, canvas: canvas.current, width: 320, height: 160, box, shapes: [{ d, paint: "var(--chart-1)" }] }); void motion.intro("sweep"); return () => motion.stop(); }, [d, box]); return (

); } ``` ## Texture > Sets how the parts inside it draw their color, like charts, meters, and buttons: dots, a gradient, or grain, with a soft glow on dark pages. - Name: `dither` - Status: beta - Categories: motion, display - File: the install writes `dither.tsx` to your `ui` alias, `@/components/ui` by default. - Gallery: https://txbrendan.dev/components/dither - Registry item: https://txbrendan.dev/r/dither.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/dither ``` ### Use it for - A dashboard, a status page, or a landing page that wants a texture on its charts and meters. - Wrap a card, a section, or the whole app in Texture. Every part inside that has a texture prop draws its color that way. Dither is dots, gradient fades from the full color to a faint wash, and grain is fine speckle. - Hover a gradient or grain part to answer the pointer: gradient's full color runs down the part, and grain fills in to solid. With reduced motion, gradient fades in place. - Pass texture on one part to change just that part, with no wrapper. - Pass texture="flat" on a part, or on an inner Texture, to keep it flat inside a Texture. - Dither is the old name for Texture, and it still works. - Pass fill, start, line, intro, hover, or idle to set how every Area Chart inside lays out and moves its dots. Each sets a --dither- variable, like --dither-intro, so the same choice can sit on \ in CSS. Bar Chart reads fill, intro, hover, and idle. Its bars have no line or start. - Parts that take texture: Sparkline, Progress, Ring Progress, Button, Avatar, and Slideshow take all four. Bar Chart and Area Chart take flat and dither, and draw flat under gradient or grain. - A change of texture fades one into the other where it sits, over --motion-duration-slow. A box that moves --dither itself, like a card that cycles between flat and dots, sets --dither-fade: 0s on itself, so the parts inside follow it with no second fade. - A chart of your own. Put DitherBoxMask in its SVG defs with the plot's box, and mask the filled shapes with it. The dots snap to the plot and thin toward its bottom. Pass thin "none" for even dots, thin "dense" for dots solid at the top that stay dense longer, or a box's from with thin "from" to thin from a bar's own top. Dither Motion moves them. ### Avoid it for - Text people must read. Textures thin out the shapes, so keep body text, labels, and numbers flat. - Saying something only with a texture. It is a look, and the part still says its value in text or its name. - A dense table or form. The texture adds noise where people need to scan. - An animation class of your own on a dithered part, like a pulse while it loads. The dots' intro sets that part's animation, so one of the two is lost. Put yours on a wrapper around the part. ### Props - `texture`: `"flat" | "dither" | "gradient" | "grain"`. Default `"dither"`. The texture every part inside draws. "flat" turns it off again inside another Texture. - `fill`: `"scatter" | "steps"`. How the dots in every Area Chart and Bar Chart inside thin toward the bottom: one by one, or in 8 even steps. Its own fill wins. - `start`: `"fade" | "gap"`. How every Area Chart inside starts: fading in from the axis, or 16 px in from it. Its own start wins. - `line`: `"fade" | "dots"`. How each Area Chart line inside starts: fading in, or breaking into dots. Its own line wins. - `intro`: `"fade" | "sweep" | "rain" | "ripple" | "pop" | "fall"`. How the dots in every Area Chart and Bar Chart inside come in. Its own intro wins. - `hover`: `"fill" | "none"`. Whether hidden dots fill in near the pointer, in every Area Chart and Bar Chart inside. Its own hover wins. - `idle`: `"none" | "wave" | "twinkle" | "breathe" | "drift"`. What the dots in every Area Chart and Bar Chart inside do at rest. Its own idle wins. - `children`: `ReactNode`. The parts that take the texture. - `className`: `string`. Extra classes. Texture draws no box of its own, since it is display: contents. ### Accessibility - Texture changes only how color is drawn. Names, roles, values, and keyboard behavior stay the same. - Texture adds no box, so it never changes layout, focus order, or what a screen reader hears. - A textured shape keeps a faint wash of its color under the dots, gradient, or grain, so it still reads as one piece. - Hover only runs on screens that can hover, so a tap never leaves it stuck. It is a fade, and with reduced motion gradient fades in place instead of running down. - The glow shows only on dark pages, through --elevation-glow, which is 0px in light. - When a dithered part first shows, its dots come in one at a time, over 40% of --motion-pulse-duration, and only once. A part further down the page waits until it starts to come on screen, then plays at the same pace however fast it was scrolled to. Button and Avatar wait with CSS alone, in browsers that can tie an animation to scrolling, and play on mount in the rest. - Button and Avatar follow their nearest scrolling box, and a box with overflow hidden or auto counts as one even when it cannot scroll. Inside such a box, their dots wait for the box to scroll them into view, and play on mount when they already sit in its view, even while the box itself is off screen. A box with overflow-clip still clips but is not a scrolling box, so parts inside it wait for the page. - With reduced motion or motion off, the pulse is 0s, so every dot shows at once. A print shows every dot. - A change of texture is a fade, so reduced motion keeps it. With motion off it swaps at once. ### Examples #### A dithered dashboard card ```tsx ``` #### Gradient meters ```tsx ``` #### One part, no wrapper ```tsx ``` #### Keep one part flat ```tsx ``` ## Donut Chart > A ring split into slices that show how parts make up a whole, with the total in the middle and every value in the legend. - Name: `donut-chart` - Status: beta - Categories: charts - File: the install writes `donut-chart.tsx` to your `ui` alias, `@/components/ui` by default. - npm packages: `recharts`, `react-is`. The install adds them. - Other registry items: `@txbrendan/chart`, `@txbrendan/skeleton`. The install adds them. - Gallery: https://txbrendan.dev/components/donut-chart - Registry item: https://txbrendan.dev/r/donut-chart.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/donut-chart ``` ### Use it for - Showing how two to five parts make up one whole, like visitors by browser or seats by plan. - Pass data with one object per slice, the categoryKey that names each slice, and the valueKey that sizes it. - Map slice names to labels and colors with config, like { chrome: { label: "Chrome" } }. - Pass centerLabel to say what the total in the middle counts. ### Avoid it for - Comparing sizes that are close. People judge angles poorly. Use BarChart. - More than five slices. The theme has five chart colors. Group the rest into Other. - Values that do not add up to a whole, or negative values. Use BarChart. - Showing change over time. Use LineChart or AreaChart. ### Props - `data`: `TData[]`. One object per slice, like { browser: "chrome", visitors: 275 }. - `categoryKey`: `keyof TData`. The field that names each slice. - `valueKey`: `keyof TData`. The number field that sizes each slice. - `config`: `{ [slice: string]: { label: string; color?: string } }`. Labels and colors by slice name. A slice it leaves out shows its name and takes the next chart color. - `title`: `ReactNode`. A visible title. It names the chart. TypeScript requires title, aria-label, or aria-labelledby. - `aria-label`: `string`. Names the chart when it has no visible title. - `centerLabel`: `string`. A word under the total in the middle, like "Visitors". - `size`: `"sm" | "md" | "lg"`. Default `"md"`. Height: 5, 7, or 9 times --control-h-md, so density scales it. The ring and the total scale with it. - `valueFormat`: `Intl.NumberFormatOptions`. Formats values in the tooltip, the legend, and the middle. - `locale`: `string`. Default `"en-US"`. The locale for numbers. Fixed, so server and browser print the same text. - `loading`: `boolean`. Default `false`. Shows a skeleton ring at the same size, and holds the legend with config names and placeholder values. When data arrives, the ring fades out while the slices draw in. - `error`: `ReactNode`. Shows this message in place of the chart. true shows a default message. - `onRetry`: `() => void`. Shows a retry button under the error. - `emptyText`: `ReactNode`. Default `"No data yet"`. Shown when there is no data, or every value is 0. - `className`: `string`. Extra classes. Later classes win, so className='h-96' replaces the height. ### Accessibility - Renders a \
named by its title, or by aria-label. TypeScript requires one. - The legend is a list of every slice with its value in text, so the numbers do not depend on color or angle. - The total in the middle is text, and screen readers read it after the chart. - Recharts' keyboard layer stays on: Tab focuses the chart, the arrow keys move between slices, and the tooltip reads each one out. The ring is one tab stop. - Keeps one height while it loads, draws, fails, or has no data, so the page does not move. When the page prints, it asks the browser to keep a chart that fits on one page whole. In the light theme, it asks the browser to print legend dots and loading shapes even with backgrounds off. - Slice colors come from --chart-1 to --chart-5, which the theme tests hold to 3:1 against the page. - Slices sweep in over three times --motion-duration-base, once the chart is on screen. They finish at once when the page prints. At 0ms they draw at once, and Recharts skips the animation for reduced motion. ### Examples #### Slices with a label in the center ```tsx ``` #### Currency ```tsx ``` #### While it loads, and when it fails ```tsx refetch()} /> ``` ## Duty Slot > One volunteer duty on one day, as a row in a card: its icon and name, what it involves, who is on it, and where it stands, ending in the quickest fix. - Name: `duty-slot` - Status: beta - Categories: sport, display - File: the install writes `duty-slot.tsx` to your `ui` alias, `@/components/ui` by default. - npm packages: `lucide-react`. The install adds them. - Other registry items: `@txbrendan/avatar`, `@txbrendan/hover-actions`, `@txbrendan/status-text`, `@txbrendan/suggestion`. The install adds them. - Gallery: https://txbrendan.dev/components/duty-slot - Registry item: https://txbrendan.dev/r/duty-slot.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/duty-slot ``` ### Use it for - One row per duty, in a Card: refreshments, setup, first aid, the front desk, photos. - The screen keeps who is on what and passes state. Confirmed is quiet. Waiting for a reply ends in Remind, Needs cover in Find cover, and Nobody yet in Find someone. - Pass suggest with the best person to ask and why. Accepting reads Asked at once, with Undo, and onAsk runs once the window ends. Move the duty to asked, with that person, when it lands. - Pass out with who dropped out and what they said. It shows in the peek on Needs cover, so the row never repeats it. - Pass date for a list across days, like a month of Mondays. ### Avoid it for - Your own undo timer for the ask, the reminder, or Withdraw. Each waits out its window in the shared result engine, so ⌘Z takes it back. - Saying who dropped out in detail as well. The peek already holds it. - Touch-only screens with no other way to swap or withdraw. A tap on the row shows its hover actions, but offer them on the duty's own page too. ### Props - `duty`: `string`. The duty, like "Refreshments" or "Setup". - `icon`: `ReactNode`. The duty's icon, in ink. Default a clipboard. - `detail`: `string`. What it involves, like "Chairs and screens before 9". - `date`: `string`. A date column, for a list across days, like "Mon 5". - `person`: `{ person: string; photo?: string } | null`. Who is on it, or who was asked. - `state`: `"confirmed" | "asked" | "cover" | "open"`. Where it stands. Default confirmed with a person, open without one. - `out`: `{ person: string; photo?: string; said?: string }`. Who dropped out and what they said, for the peek on Needs cover. - `suggest`: `{ person: string; photo?: string; reason?: string; message?: string }`. The best person to ask, why, and the first message they get. Shows as a Suggestion while the duty needs someone. - `onAsk`: `(person: { person: string; photo?: string; message?: string }) => void | Promise`. Asks the suggested person once the undo window ends. A failed promise turns the chip into Retry. - `onFindCover`: `() => void`. The fix for Needs cover and Nobody yet. - `onRemind`: `() => void | Promise`. Reminds the person who has not replied, once the undo window ends. - `onWithdraw`: `() => void | Promise`. Withdraws the ask once its undo window ends. Tell the person there. - `onSwap`: `() => void`. A hover action on a confirmed duty. - `divider`: `boolean`. Default `false`. A hairline above the row, inset from the card's edges. - `index`: `number`. Place in a list. Rows fade up one after another as they first show. - `className`: `string`. Extra classes. Later classes win. ### Accessibility - The duty, its detail, who is on it, and the status are all text, in reading order. - Each status is words in its tone's soft text, which the theme holds to 4.5:1. The tones share colors, so the words say which. - Each fix is a native button named for what it does, like "Remind Tom Hale", with the same words in its tooltip. - Needs cover is a peek trigger. Hover, focus, or a tap opens who dropped out, and Esc closes it. - The hover actions stay in the Tab order, and focus inside them shows the bar. - The ask, the reminder, and Withdraw each say what happened once, through the page's one polite live region. ### Examples #### Confirmed, waiting for a reply, and needs cover ```tsx } detail="Morning break and lunch" person={{ person: "Sue Hale" }} onSwap={swap} /> } detail="Chairs and screens before 9" person={{ person: "Tom Hale" }} state="asked" onRemind={() => remind("setup")} onWithdraw={() => withdraw("setup")} divider /> } state="cover" out={{ person: "Mark Clarke", said: "Can't do it · Tue 29 Sep" }} suggest={{ person: "Cal Nash", reason: "First aid trained, and free on Thursday" }} onAsk={(who) => ask("first-aid", who)} onFindCover={() => openCover("first-aid")} divider /> ``` ## Editor > Long writing in a field's frame, with a glass toolbar over selected words and pasting that keeps only clean HTML. - Name: `editor` - Status: beta - Categories: forms - File: the install writes `editor.tsx` to your `ui` alias, `@/components/ui` by default. - Other registry items: `@txbrendan/field-frame`, `@txbrendan/tool-button`. The install adds them. - Gallery: https://txbrendan.dev/components/editor - Registry item: https://txbrendan.dev/r/editor.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/editor ``` ### Use it for - Newsletters, minutes, reports, and announcements: writing with headings, lists, and links. - Save from onChange. It gets clean HTML, "" when empty, and the words. - Show saving with status, like a StatusText that says Saved 18:04. It ends the label's line. - Show the saved HTML anywhere with Prose, in the same look. ### Avoid it for - A message to people. Use Composer. - A line or two of plain text. Use Textarea or Input. - Rich layouts, tables, or images. It keeps paragraphs, headings, lists, bold, italic, and links only. ### Props - `value`: `string`. HTML. Controlled: the editor only reloads when this differs from what it last sent. - `defaultValue`: `string`. HTML to start with. - `onChange`: `(html: string, info: { text: string; words: number }) => void`. Clean HTML ("" when empty) and the words, on every change. - `label`: `ReactNode`. Names the writing area. - `hint`: `ReactNode`. A short note under the writing area. It describes it. - `error`: `ReactNode`. Replaces the hint while set, in red, and marks the writing area invalid. - `placeholder`: `string`. Shown while it is empty. Never sent. - `rows`: `number`. Default `6`. The least height, in lines. It grows with its words. - `size`: `"sm" | "md" | "lg"`. Default `"md"`. Padding and label size. The words stay 13/18 and headings 16/20. - `disabled`: `boolean`. Default `false`. Locks the words. - `showCount`: `boolean`. Default `false`. A word count under the right edge. - `status`: `ReactNode`. Ends the label's line, like a saving status. - `ref`: `Ref`. Reaches the writing area. - `id`: `string`. Goes on the writing area, so the label still points at it. aria-\, data-\, and handlers go there too. - `className`: `string`. Extra classes on the frame. Later classes win. ### Accessibility - The writing area is a role="textbox" with aria-multiline, named by the label and described by the hint or error. - Select words and a toolbar shows over them. Alt+F10 moves into it. It is one Tab stop, and ← → Home and End move along it. - Each button says its state with aria-pressed. Its tooltip teaches its key: ⌘B, ⌘I, ⌘K, or # - or 1. then Space at the start of a line. - Esc steps back: out of the link field, then from the toolbar to the selected words, then it hides the toolbar. In a Sheet, that Esc never closes the sheet. - A link asks for its address in the toolbar. Enter applies it, and empty removes it. Only web and email addresses are linked. - Under reduced motion the toolbar moves at once. ### Examples #### A newsletter that saves as you write ```tsx Saved 18:04} onChange={(next) => save(next)} /> ``` #### Showing it ```tsx ``` ## Estimate Chart > What was expected against what came in, per period: a ring for the estimate and a dot for the actual, colored by beat, miss, or match. - Name: `estimate-chart` - Status: beta - Categories: charts - File: the install writes `estimate-chart.tsx` to your `ui` alias, `@/components/ui` by default. - npm packages: `recharts`, `react-is`. The install adds them. - Other registry items: `@txbrendan/chart`. The install adds them. - Gallery: https://txbrendan.dev/components/estimate-chart - Registry item: https://txbrendan.dev/r/estimate-chart.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/estimate-chart ``` ### Use it for - Showing a forecast next to the result for each period, like earnings per share against the estimate. - Pass data with a period, an estimate, and an actual for each row, oldest first. - Leave actual out for a period still to come. It shows its estimate ring alone. - Change data, as from tabs, and each mark glides to its new value in a wave from left to right. Periods are matched by name. - Pass matchWithin to count a near value as a match. - Pass valueFormat, like { style: "currency", currency: "USD" }, to format the tooltip and the axis. ### Avoid it for - One value per period with no forecast. Use LineChart or BarChart. - Many series at once. This chart compares one estimate with one actual. - Hundreds of periods. The marks crowd together. Show the latest periods and offer more. ### Props - `data`: `{ period: string; estimate?: number | null; actual?: number | null }[]`. One row per period, oldest first. Leave actual out for a period still to come. Periods may share a name, like Q1 in two years, and each keeps its place. An actual with no estimate draws a plain dot with an Actual key. - `title`: `ReactNode`. A visible title. It names the chart. TypeScript requires title, aria-label, or aria-labelledby. - `aria-label`: `string`. Names the chart when it has no visible title. - `valueFormat`: `Intl.NumberFormatOptions`. Formats tooltip values, and the value labels in short form, like $120B. - `locale`: `string`. Default `"en-US"`. The locale for numbers. Fixed, so server and browser print the same text. - `matchWithin`: `number`. Default `0`. An actual this close to its estimate counts as a match. - `labels`: `{ estimate?, actual?, beat?, miss?, match?: string }`. The words for each mark, in the legend and the tooltip. - `legend`: `boolean`. Default `true`. Shows the legend: the estimate ring, then Beat, Miss, and Match once any period is scored. The keys stay put when the data changes. While loading, it shows the estimate ring with Beat, Miss, and Match. - `size`: `"sm" | "md" | "lg"`. Default `"md"`. Height: 5, 7, or 9 times --control-h-md, so density scales it. - `loading`: `boolean`. Default `false`. Shows skeleton points at the same height. When data arrives, they fade out while the chart draws in. - `error`: `ReactNode`. Shows this message in place of the chart. true shows a default message. - `onRetry`: `() => void`. Shows a retry button under the error. - `emptyText`: `ReactNode`. Default `"No data yet"`. Shown when no period has an estimate or an actual. - `className`: `string`. Extra classes. Later classes win, so className='h-96' replaces the height. ### Accessibility - Renders a \
named by its title, or by aria-label. TypeScript requires one. - Tab focuses the chart. The arrow keys step through the periods, and the tooltip reads out each one: its estimate, its actual, and whether it beat, missed, or matched, with the gap in percent. - Beat, miss, and match are said in words in the legend and the tooltip, not by color alone. The estimate is a ring and the actual a filled dot, so the two differ by shape too. - The period under the pointer or the arrow keys grows a little, and a line marks it. The value labels fade back while it is read, since the tooltip carries the numbers. Escape hides the tooltip and brings them back. - The value labels have their own room at the start of the plot, so no mark covers one. Period labels at either end are nudged inside the chart, and long names are spaced so they never overlap. Right to left, the labels stay in their room. A ring its dot would almost cover is left out, and the tooltip still gives both numbers. - Marks grow in from left to right once the chart is on screen. When the data changes, each glides to its new value in the same wave, and the value labels cross-fade. When periods come or go, the others slide over first. At 0ms everything draws at once, and Recharts skips the motion for reduced motion. - Keeps one height while it loads, draws, fails, or has no data, so the page does not move. ### Examples #### Earnings per share ```tsx ``` #### Data that follows tabs ```tsx const [measure, setMeasure] = useState("share"); setMeasure(String(next))}> Per share Revenue ``` #### While it loads, and when it fails ```tsx refetch()} /> ``` ## Feature Voting > A list of ideas, each with an upvote button and its count, or an up and down vote stacked around the count. It shows how this person voted. - Name: `feature-voting` - Status: beta - Categories: forms, voting - File: the install writes `feature-voting.tsx` to your `ui` alias, `@/components/ui` by default. - Other registry items: `@txbrendan/motion`, `@txbrendan/button`, `@txbrendan/badge`, `@txbrendan/rolling-number`, `@txbrendan/tooltip`. The install adds them. - Gallery: https://txbrendan.dev/components/feature-voting - Registry item: https://txbrendan.dev/r/feature-voting.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/feature-voting ``` ### Use it for - Letting people vote on a list of ideas, like feature requests or topics for a meeting. - People can vote for as many ideas as they like. Pressing a button again takes the vote back. - Pass layout="stack" to let people vote up or down, like a forum. An up caret, the count, and a down caret stack in a column at the start of each idea, and votes is then ups minus downs, so it can go below zero. - In the stack layout, pressing the other caret moves the vote in one press. Each caret has a tooltip that says what it does, and the count rolls to its new value. - Pass each idea with its votes so far. A status like Planned shows as a badge beside the title. - The list keeps the order you pass. Sort it yourself, like by votes, when you load the data. - Return a promise from onVote to save each vote. The button and its count change at once, with savingText after the title, until the promise settles. If it rejects, the vote goes back and errorText shows under the idea. - Leave voted out to let the list keep its own state. It then counts the votes it takes, and defaultVoted marks earlier votes, with defaultDownvoted for down votes. People can press again while a vote saves, and the newest press on each idea wins, even when an older save finishes later. - Pass voted, and downvoted in the stack layout, to keep the votes in your own state, and include this person's votes in the counts you pass. Once a save succeeds, and before your onVote promise resolves, update them and the counts. Your state then decides, so if saves can finish out of order, skip one that a newer press replaced. - While a vote saves, its item has data-pending, for your own styles. A vote up sets data-voted, and a vote down data-downvoted. - For another language, pass upvoteText, downvoteText, savingText, errorText, votesText, and locale. ### Avoid it for - One question with a few fixed answers, where people pick one. Use Choice Poll instead. - Rating one thing on a scale, like 1 to 5 stars. - A single like button on a post. Use a Button with aria-pressed. - Sorting the list again while someone votes. The idea would move away from their focus. ### Props - `items`: `{ value: string; title: ReactNode; description?: ReactNode; votes: number; status?: { label: string; tone?: "neutral" | "brand" | "danger" | "success" | "warning" }; disabled?: boolean }[]`. The ideas, in the order to show them. value must be unique. votes is the count so far, this person's included. In the stack layout it is ups minus downs, and it can be below zero. disabled blocks voting on one idea, like one that has shipped. - `layout`: `"inline" | "stack"`. Default `"inline"`. inline puts one upvote button with its count at the end of each idea. stack puts an up caret, the count, and a down caret in a column at the start, so people can vote up or down. - `voted`: `string[]`. The values of the ideas this person voted up. Controlled, together with downvoted. The list shows the counts you pass as they are, plus a vote that is still saving. - `downvoted`: `string[]`. The values of the ideas this person voted down, in the stack layout. Controlled, together with voted. - `defaultVoted`: `string[]`. Earlier votes up by this person when you do not control the votes. They are already in the counts, so the list does not add them again. - `defaultDownvoted`: `string[]`. Earlier votes down by this person when you do not control the votes, in the stack layout. They are already in the counts. - `onVote`: `(value: string, voted: boolean, direction: "up" | "down") => void | Promise`. Called when someone votes on an idea (true) or takes the vote back (false), with the direction pressed. Moving a vote from up to down is one call, with true and "down". Return a promise, and the list shows the change at once with savingText until it settles. A rejection puts the earlier vote back and shows errorText under the idea. - `disabled`: `boolean`. Default `false`. Blocks every vote button. The counts still show. - `tone`: `"neutral" | "brand" | "danger" | "success" | "warning"`. Default `"neutral"`. Color of the vote buttons. A vote fills its button with it. The rest are outlined, or plain carets in the stack layout. - `upvoteText`: `string`. Default `"Upvote"`. The word that starts each upvote button's name for screen readers. In the stack layout, the up caret's tooltip shows it too. - `downvoteText`: `string`. Default `"Downvote"`. The word that starts each down caret's name for screen readers, and its tooltip, in the stack layout. - `savingText`: `string`. Default `"Saving…"`. Shown after an idea's title while its vote saves. The vote button's aria-describedby points to it. - `errorText`: `string`. Default `"Could not save your vote. Try again."`. Shown under an idea when its vote does not save. Screen readers announce it. - `votesText`: `{ zero?: string; one?: string; two?: string; few?: string; many?: string; other: string }`. Default `{ one: "{count} vote", other: "{count} votes" }`. How a count of votes reads in each plural form, with {count} for the number. Screen readers hear it in each button's name, and the button shows only the number. The list picks the form with Intl.PluralRules for locale. - `locale`: `string`. Default `"en-US"`. A language tag for the counts and the plural forms, like 'de-DE'. - `className`: `string`. Extra classes for the list. Later classes win, so className='divide-y-0' drops the lines between ideas. ### Accessibility - The ideas are a list. Each item holds the title, the details, the status badge, and the vote button. - Each vote button is a toggle button. Its name reads upvoteText, the title, and the count, like 'Upvote Dark mode 48 votes'. aria-pressed says whether this person voted. - The name comes from aria-labelledby on ids in the same item, so it is in the server HTML too. - Space and Enter vote and take the vote back, like any button. - A vote shows at once, so there is no spinner and no aria-busy. savingText shows after the title until the vote saves, and the button's aria-describedby points to it. Every button stays ready, so people can press again. - A failed save shows errorText under the idea in a role="alert" message. The button's aria-describedby points to it, and focus stays on the button. - disabled, on the list or on one idea, takes those buttons out of the tab order. - A voted button is filled and the rest are outlined, so the vote does not rest on color alone. - A changed count fades in over --motion-duration-base. data-motion="off" makes it instant. Reduced motion drops the slide but keeps the fade. - In the stack layout, each caret is a toggle button with its own aria-pressed. Their names read the direction, the title, and the count, like 'Upvote Dark mode 48 votes' and 'Downvote Dark mode 48 votes'. The number between them is hidden from screen readers, since both names hold it. - Each caret's tooltip says what it does. It opens after the pointer rests 150 ms, at once on keyboard focus, and Escape closes it. Touch shows none. - The stack layout's count rolls to each new value. Reduced motion and data-motion="off" jump straight to it. - Every word has a prop with an English default: upvoteText, downvoteText, savingText, errorText, and votesText. locale formats the counts and picks each plural form. ### Examples #### A list that keeps its own state ```tsx ``` #### Save votes yourself ```tsx "use client"; const items = [ { value: "dark-mode", title: "Dark mode", votes: 48 }, { value: "export", title: "Export to a spreadsheet", votes: 31 }, ]; // The list shows each vote at once and counts it. If this throws, it puts the vote back and says so. // It keeps its own state, so the newest press on an idea wins even when an older save finishes later. async function save(value: string, voted: boolean) { // Replace this with your own request. fetch does not throw on a server error, so check ok. const response = await fetch("/api/votes", { method: "POST", body: JSON.stringify({ idea: value, voted }) }); if (!response.ok) throw new Error("The vote did not save."); } function IdeaBoard() { return ; } ``` #### Statuses and a shipped idea ```tsx ``` #### Vote up or down in a stacked column ```tsx "use client"; const items = [ { value: "dark-mode", title: "Dark mode", description: "Easier on the eyes at night.", votes: 48 }, { value: "sounds", title: "A sound for every message", votes: -4 }, ]; // voted is false when the vote is taken back, so the idea then has no vote from this person. async function save(value: string, voted: boolean, direction: "up" | "down") { const response = await fetch("/api/votes", { method: "POST", body: JSON.stringify({ idea: value, vote: voted ? direction : null }) }); if (!response.ok) throw new Error("The vote did not save."); } function IdeaBoard() { return ; } ``` #### In another language ```tsx ``` ## Field Frame > The frame every field wears: a label above, the control, and a hint or an error under it, wired up for screen readers. Also exports FieldButton, the field-shaped trigger for lists and pickers. - Name: `field-frame` - Status: beta - Categories: forms - File: the install writes `field-frame.tsx` to your `ui` alias, `@/components/ui` by default. - Other registry items: `@txbrendan/motion`, `@txbrendan/input`. The install adds them. - Gallery: https://txbrendan.dev/components/field-frame - Registry item: https://txbrendan.dev/r/field-frame.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/field-frame ``` ### Use it for - Frame any field with it, so every form reads, sizes, and announces the same way. - Give the frame the control's id. The label gets \-label and the hint or error gets \-note. - Spread fieldIds(id, { label, hint, error, control }) on the control. It sets aria-describedby, aria-invalid, and, for a button or a group, aria-labelledby. A button cannot take aria-invalid, so it gets data-invalid, which draws the red edge. - fieldIds lives in a client file, so call it from a client component. In a server component, write the same ids by hand: aria-describedby="\-note", and aria-labelledby="\-label \" for a button. - control="input" for a native input or textarea. The label is a real \ that points at it. - control="button" for a trigger whose text is its value, like a picker. It reads as the label and the value: "Room, Boardroom". Pressing the label focuses the button and does not open it. - control="custom" for a group or an editor. The label names it. Pass onLabel to say what pressing the label focuses. - Use FieldButton for anything that opens a list or a picker from a field. It has the field's box and states, and a chevron that turns over while open. - Put a saving status in status, and a counter like "12/80" in aside. ### Avoid it for - A label you hide. Every field needs a name people can see. - Putting the error only in the red edge. Pass it as error, so it is said and shown in words. - A form section with several fields. Use a heading or a fieldset for the section, and a frame for each field. ### Props - `id`: `string`. Required. The control's id. The label and the note take ids built from it. - `label`: `ReactNode`. Names the control. Pressing it focuses the control. - `hint`: `ReactNode`. A short note under the control that describes it. - `error`: `ReactNode`. Replaces the hint while set, in red. Announced once each time a new message appears. - `size`: `"sm" | "md" | "lg"`. Default `"md"`. Label and note text size, and the gaps. Match the control's size. - `control`: `"input" | "button" | "custom"`. Default `"input"`. What the frame holds, which decides how the label names it. - `onLabel`: `() => void`. What pressing a label that is not a native label does. By default it focuses the element with the id. - `aside`: `ReactNode`. Ends the note line, like a counter. Muted, with figures that keep their width. - `status`: `ReactNode`. Ends the label line, like a saving status. Kept to the label's height. - `disabled`: `boolean`. Default `false`. Dims the label to match a disabled control. - `className`: `string`. Extra classes for the frame. Later classes win. ### Accessibility - For control="input" the label is a native \, so clicking it focuses the input and screen readers read it as the name. - For a button or a group the label is plain text with an id, named through aria-labelledby. A native label would press the button. - The hint or error has the id \-note. fieldIds points the control's aria-describedby at it. - The error has role="alert". It mounts fresh for each new message, so screen readers say it once when it appears. - The error color is the danger tone's soft text, which the theme tests hold to 4.5:1. The words carry the meaning, not only the color. - FieldButton sets aria-haspopup, aria-expanded, and aria-controls while open. A popup trigger, like PopoverTrigger, sets them itself instead. ### Examples #### A text field with a hint ```tsx ``` #### An error in place of the hint ```tsx ``` #### A picker trigger ```tsx Boardroom ``` ## File Drop > Files in: an empty slot with a dashed edge. While a file is over it, it takes the selection look and says "Drop to add". A press anywhere on it opens the picker. - Name: `file-drop` - Status: beta - Categories: dates, forms - File: the install writes `file-drop.tsx` to your `ui` alias, `@/components/ui` by default. - Other registry items: `@txbrendan/motion`. The install adds them. - Gallery: https://txbrendan.dev/components/file-drop - Registry item: https://txbrendan.dev/r/file-drop.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/file-drop ``` ### Use it for - Bringing files in, like a member list, an order list, or a team photo. - Say what it is in title: "Drop your member list here". Say the types and the limit in hint: "CSV or Excel · up to 10 MB". - The parent keeps the file list and does the uploading. Show each file in a file row. - accept is checked for dropped files too, and multiple keeps only the first when it is off. Files of another type are left out, and it says so in red. - Check size and contents on your server too. It only reads what the browser gives it. ### Avoid it for - A person's own photo. Use a photo field, which places and crops it. - A link or text to paste. Use an input. ### Props - `onFiles`: `(files: File[]) => void`. The files picked or dropped, already checked against accept and multiple. - `accept`: `string`. The types it takes, like ".csv,.xlsx" or "image/\". The picker shows only these, and drops are checked too. - `multiple`: `boolean`. Default `false`. Takes several files at once. Off, it keeps the first. - `title`: `ReactNode`. Default `"Drop a file here"`. Say what it is: "Drop your member list here". - `action`: `ReactNode`. Default `"choose a file"`. The words of the button that opens the picker. - `dropTitle`: `ReactNode`. Default `"Drop to add"`. Shown while a file is over it. - `hint`: `ReactNode`. The types and the limit, like "CSV or Excel · up to 10 MB". - `size`: `"sm" | "md" | "lg"`. Default `"md"`. Padding and text size. - `disabled`: `boolean`. Default `false`. Blocks the picker and drops. A file dropped on it is still caught, so the browser never opens it instead. - `className`: `string`. Classes for the zone. ### Accessibility - The one Tab stop is the "choose a file" button. Its description is the title and the hint, so it is heard as "choose a file, Drop your member list here". - A press anywhere on the zone opens the same picker, for the mouse and touch. - A polite status says what was added, like "Added Members 2026.csv". - Files of another type are left out, and a red message says so once. - While a file is over it, the dashed edge turns solid, so forced-colors mode shows the change too. ### Examples #### A member list ```tsx console.log(files)} /> ``` ## File Row > One file in a list: an icon by type, the name, "412 KB · 214 rows", and who added it, with their photo. It shows an upload's progress, its failure and the fix, or that it is done. - Name: `file-row` - Status: beta - Categories: dates, forms - File: the install writes `file-row.tsx` to your `ui` alias, `@/components/ui` by default. - npm packages: `lucide-react`. The install adds them. - Other registry items: `@txbrendan/motion`, `@txbrendan/avatar`, `@txbrendan/button`, `@txbrendan/status-text`, `@txbrendan/tooltip`. The install adds them. - Gallery: https://txbrendan.dev/components/file-row - Registry item: https://txbrendan.dev/r/file-row.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/file-row ``` ### Use it for - Each file a file drop takes in, and files already attached, like a member list or a handbook. - The parent keeps the list and does the uploading. Pass status and progress as it goes. - Pass by with who added it. Their photo shows, or their initial until there is one. - When the connection dropped, pass onRetry: a retry icon, named "Try again", follows "Couldn't upload". - When the file itself is the problem, say why in error and pass onReplace: an upload icon picks a new file instead, since the same file fails the same way. - Pass divider on every row but the first. ### Avoid it for - Bringing files in. Use a file drop, then show each file in one of these. - A person's photo. Use a photo field. - A long list to sort and filter. Use a table. ### Props - `name`: `string`. The file's name. Its extension picks the icon: a sheet, a document, an image, a video, an archive, or a plain file. - `bytes`: `number`. The size in bytes, shown as "412 KB". A KB is 1024 bytes. - `meta`: `ReactNode`. Extra detail after the size, like "214 rows". - `by`: `{ person: string; photo?: string }`. Who added it, shown with their photo. - `status`: `"uploading" | "done" | "error"`. Where the upload is. Without one, the row just lists the file. - `progress`: `number`. 0 to 1 while uploading. A thin bar under the row fills, and the percent shows after the name. - `error`: `ReactNode`. Why it failed, under the name, in ink: "Row 12 has no email address". - `onRemove`: `() => void`. Shows a remove button at the end of the row. - `onRetry`: `() => void | Promise`. On a failure: a retry icon, named "Try again". Return a promise, and it waits on it. - `onReplace`: `(file: File) => void`. On a failure caused by the file: an upload icon opens the picker and hands back the new file. It takes the retry's place. - `accept`: `string`. File types for onReplace's picker, like ".csv". - `divider`: `boolean`. Default `false`. A line above the row. - `size`: `"sm" | "md" | "lg"`. Default `"md"`. Padding and text size. - `className`: `string`. Classes for the row. ### Accessibility - Every status shows in words: "Uploading 42%", "Uploaded" with a green check, or "Couldn't upload" in red. - The bar is a progressbar named "Uploading" plus the file's name, with its percent. - A polite status says when a file uploads or fails, once, as it happens. - The retry and replace icons are buttons named "Try again" and "Replace file", with tooltips. - Remove is a button named "Remove" plus the file's name, so a list of them is told apart. - In forced-colors mode the bar's fill draws as a border, and the type icon keeps an edge. ### Examples #### Uploaded ```tsx {}} /> ``` #### The file is the problem ```tsx console.log(file)} /> ``` ## Finals Board > Finals day on one board: two semi-finals feed the cup final and the bronze final, each pitch's matches sit on a shared timeline, and a hold moves the later matches on the final's pitch. - Name: `finals-board` - Status: beta - Categories: sport, display - File: the install writes `finals-board.tsx` to your `ui` alias, `@/components/ui` by default. - npm packages: `@base-ui/react`, `lucide-react`. The install adds them. - Other registry items: `@txbrendan/avatar`, `@txbrendan/card`, `@txbrendan/motion-timing`, `@txbrendan/switch`, `@txbrendan/team-flag`, `@txbrendan/tool-button`. The install adds them. - Gallery: https://txbrendan.dev/components/finals-board - Registry item: https://txbrendan.dev/r/finals-board.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/finals-board ``` ### Use it for - Running a cup's finals day: record each winner as it happens, and hold the final's pitch when it runs late. - Pass the four sides as the semi-finals pair them, and where and when each match is played. The slot and the hold's length come from the competition. - Leave out schedule.bronze when there is no bronze final. - Give each team its kit colors. A team without them shows its initials. - Pass value and onChange to keep results in your data, or defaultValue to let the board keep its own. The same goes for held, onHold, and defaultHeld. ### Avoid it for - A draw bigger than four. Use KnockoutBracket, which takes any number of rounds. - Showing a past finals day. Nothing here should be pressed then: use KnockoutBracket or MatchCard. - A league day. Nothing feeds anything, so there is no bracket to fill in. ### Props - `semis`: `[[FinalsTeam, FinalsTeam], [FinalsTeam, FinalsTeam]]`. The four sides, as the semi-finals pair them. Each is { id, name, colors?, pattern? }. - `schedule`: `{ sf1, sf2, final, bronze? }`. Each match's { pitch, kickoff, title? }, with kickoff like "13:00". Without bronze, there is no bronze final. - `minutes`: `number`. Default `40`. How long each match holds its pitch: the competition's slot. - `value`: `FinalsResults`. Winners by match, as team ids, controlled. Like { sf1: "rovers", final: null }. - `defaultValue`: `FinalsResults`. Winners at the start, when the board keeps its own. - `onChange`: `(results: FinalsResults) => void`. Hears every result, and the old results back on ⌘Z. - `held`: `boolean`. Whether the final's pitch is held now, controlled. - `defaultHeld`: `boolean`. Default `false`. Whether it starts held, when the board keeps its own. - `onHold`: `(held: boolean) => void`. Hears the hold switch. - `holdMinutes`: `number`. Default `15`. How far a hold moves the matches on the final's pitch that have no result when it starts. A moved match keeps its new kickoff once recorded. - `className`: `string`. Extra classes. Later classes win. ### Accessibility - Cup bracket and Day control are groups named by their titles. - Each match's two teams are a radio group, named by the match and described by its pitch and kickoff. Tab reaches the group, the arrow keys move between the teams, and the chosen team is the winner. - A recorded match also names its winner in text, like "Rovers won.", which the group's description reads with its pitch and kickoff. - A final waits as a plain group that names who it waits for, like "Semi-final 1 winner", until both semi-finals are in. - One live line says each result and each hold once, like "Semi-final 1: Rovers won. Cup final and Bronze final cleared." ⌘Z says the undo in the page's own region. - ⌘Z works with focus on a team, since the teams are not text fields. - A held match's new kickoff has "+15 min" beside it, in words as well as amber, so it shows in forced colors. - The timeline is a named region with a list per pitch. It takes a Tab stop only when it scrolls sideways. - The champion types itself in only when the final is recorded on the page, never on load. Screen readers hear the name whole. Under reduced motion or with motion off, it shows at once. ### Examples #### Four teams on two pitches, with a bronze final ```tsx ``` #### Results in your data ```tsx const [results, setResults] = useState({}); const [held, setHeld] = useState(false); ``` ## Form Guide > A team's last results as W, D, and L on tinted squares, oldest first, with a peek that lists the scores, latest first. - Name: `form-guide` - Status: beta - Categories: sport, display - File: the install writes `form-guide.tsx` to your `ui` alias, `@/components/ui` by default. - Other registry items: `@txbrendan/hover-card`. The install adds them. - Gallery: https://txbrendan.dev/components/form-guide - Registry item: https://txbrendan.dev/r/form-guide.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/form-guide ``` ### Use it for - A team's recent results in a table row, a fixture card, or a team header. - Pass results oldest first. The latest sits on the right. - Add score, opponent, away, and date to each result, and the guide opens a peek that lists them, latest first. - In a table or list, mark each row with data-peek-row. The peek then opens beside the row, so the rows above and below stay in reach. - Use size='sm' in dense tables. ### Avoid it for - A full results list. Use a table, with the date, the opponent, and the score in columns. - Anything that is not a win, a draw, or a loss. Use Badge. ### Props - `results`: `{ result: "W" | "D" | "L"; score?: string; opponent?: string; away?: boolean; date?: string }[]`. Required. The last results, oldest first. A win is green, a loss red, a draw ink, and the letter always says it. An empty list shows a dash. - `size`: `"sm" | "md" | "lg"`. Default `"md"`. Squares of 18, 22, or 28px at the default density. - `aria-label`: `string`. Default `"Form"`. What screen readers hear before the results. - `className`: `string`. Extra classes for the row of squares. Later classes win. ### Accessibility - Screen readers hear 'Form, oldest to latest: won, won, lost'. The letters say the result, so color is never the only signal. - With no details it is role="img" with that name, and no tab stop. - With details it is a HoverCard trigger: a focusable role="button" with that name and aria-haspopup="dialog". - Focus opens the peek at once, a short rest of the pointer opens it, and so does a tap. Enter or Space moves focus into it, and Esc closes it and puts focus back. - ↑ and ↓ step to the peek above or below, as on every peek, and only one peek shows at a time. - The peek is a dialog named 'Last 5, latest first', which it also shows as its title. It lists each result as a line of text. - The squares use the tones' soft colors, which the theme holds to 4.5:1 with their letters. ### Examples #### Results only ```tsx ``` #### With a peek ```tsx ``` ## Funnel Chart > Steps that narrow, like joining or trials, as numbered rows with a pill bar, each step's share of the first, and how many stopped before it. - Name: `funnel-chart` - Status: beta - Categories: charts - File: the install writes `funnel-chart.tsx` to your `ui` alias, `@/components/ui` by default. - Other registry items: `@txbrendan/breakdown-list`, `@txbrendan/chart`. The install adds them. - Gallery: https://txbrendan.dev/components/funnel-chart - Registry item: https://txbrendan.dev/r/funnel-chart.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/funnel-chart ``` ### Use it for - Steps people pass through in order, where some stop at each step: sign-up forms, trials, a checkout. - Pass stages, first to last, each with a label and a value, and a title or aria-label. - Each bar is its share of the first step. Each step after the first says how many stopped before it. - Give a stage meta to replace the automatic 'stopped' line. - Pass value: null for a step with no figure yet. It shows a dash, not a zero. ### Avoid it for - Parts of a whole or a ranking. Use BreakdownList. Its rows take the same shape. - Steps that do not narrow, like a timeline. Use a list or a table. - A trend over time. Use LineChart or AreaChart. ### Props - `stages`: `{ id?: string; label: string; value: number | null; meta?: ReactNode }[]`. Required. The steps, first to last. The same shape as a BreakdownList row, so one set of rows fits either. - `title`: `ReactNode`. A visible title. It names the funnel. TypeScript requires title, aria-label, or aria-labelledby. - `aria-label`: `string`. Names the funnel when it has no visible title. - `valueFormat`: `Intl.NumberFormatOptions | ((value: number) => string)`. How each step's value prints, like v => \`${v} people\`. Options work from a server component. A function works from a client component only. - `locale`: `string`. Default `"en-US"`. The locale for numbers. - `loading`: `boolean`. Default `false`. Shows placeholder rows, as many as stages, or three. - `emptyText`: `ReactNode`. Default `"No data yet"`. Shown when stages is empty. - `className`: `string`. Extra classes for the card. Later classes win. ### Accessibility - Renders a \
named by its title, or by aria-label. TypeScript requires one. The steps are an ordered list. - Each step reads as its label, its value, and its share of the first step, then its meta, like 'Paid: 51, 80% of the first step, 13 stopped before this step'. - A step with no value reads 'no figure', and shows a dash with no bar. - The bars are hidden from screen readers. The track is quiet, so the numbers in text carry the meaning. - Bars use --chart-1, which the theme holds to 3:1 on the page. - Bars grow in once the funnel is on screen, over three times --motion-duration-base. Reduced motion and motion off draw them at once. ### Examples #### Each step, with its share of the first ```tsx ``` #### With its own lines ```tsx ``` ## Gantt Chart > Shows items as bars across a date range, in groups, with a fixed name column, week ticks, and a today marker. Use it to see when work runs and how far along it is. - Name: `gantt-chart` - Status: beta - Categories: charts, data, dates - File: the install writes `gantt-chart.tsx` to your `ui` alias, `@/components/ui` by default. - Other registry items: `@txbrendan/glide-highlight`, `@txbrendan/skeleton`, `@txbrendan/tooltip`. The install adds them. - Gallery: https://txbrendan.dev/components/gantt-chart - Registry item: https://txbrendan.dev/r/gantt-chart.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/gantt-chart ``` ### Use it for - Work that spans days or weeks, like projects by stage, where start, end, and progress matter. - Pass groups, each with its items. An item takes a label, start and end days, and progress from 0 to 1. - Pass days as ISO strings, like '2026-10-13'. - Pass onItemOpen so each bar is a button that opens its item, like a Sheet. - Put a caption on a bar for a short count, like '45% · 9/20'. It shows beside the bar, so the fill reads whole. - The chart has loading and empty states. A failed load is yours: show a Notice with a retry in its place. - To build your own rows, like a list that turns into this chart, wrap them in GanttScale and use GanttHeader, GanttTrack, GanttGrid, and GanttToday for the date side. ### Avoid it for - Times within one day, like bookings. Use Time Grid. - A list of events with no length. Use Timeline. - One value over time. Use LineChart or AreaChart. - Dragging bars to new dates. Bars open, they do not move. ### Props - `groups`: `{ id: string; title: ReactNode; items: GanttItem[] }[]`. The rows, in groups, like stages. Each group shows its title and count, then its items. A group with no items still shows its title. - `GanttItem`: `{ id: string; label: string; meta?: ReactNode; start: string | Date; end: string | Date; progress?: number; tone?: "neutral" | "brand" | "danger" | "success" | "warning"; caption?: ReactNode }`. One row. The bar runs from the start of start to the end of end. progress, from 0 to 1, fills that share in tone, neutral by default. caption shows beside the bar, and defaults to the progress as a percent. - `aria-label`: `string`. Names the chart for screen readers. - `start`: `string | Date`. Default `the earliest item's start`. The first day shown. - `end`: `string | Date`. Default `the latest item's end`. The last day shown. - `today`: `string | Date`. Places the today marker, a pill with the date in the header and a line down the chart. Left out, there is no marker. Pass it from the server, so the first render matches. - `locale`: `string`. Default `"en-US"`. The locale for dates and percents. One it does not know falls back to en-US. - `timeZone`: `string`. Default `"UTC"`. The time zone that puts a Date, or a string with a time, on its day. ISO days, like '2026-10-13', stay as they are. One it does not know falls back to UTC. - `loading`: `boolean`. Default `false`. Shows placeholder rows while the items load. - `empty`: `ReactNode`. Default `"Nothing scheduled yet."`. What shows when no group has items. Give it a next step, like a button that adds one. - `onItemOpen`: `(id: string) => void`. Makes each bar a button that opens its item, and lets a press on its row open it. Called with the item's id. - `GanttScale`: `GanttScaleProps`. Part. Holds start, end, today, locale, and timeZone for the parts inside, and sets the layout variables. Put it around your own scroll box and rows. It is a size container. - `GanttHeader`: `GanttHeaderProps`. Part. The dates along the top, a tick at each Monday. A tick near today gives way to the today pill. The right cell of the header row. - `GanttTrack`: `GanttTrackProps`. Part. The right cell of one row, with its item's bar. Takes item, index (the row's place from the top across every group, which sets when its bar arrives), and onItemOpen. - `GanttGrid`: `GanttGridProps`. Part. Faint week lines over the date side. Put it first inside the positioned box that holds the rows. - `GanttToday`: `GanttTodayProps`. Part. The today marker over the date side. It arrives last: a pill with the date in the header, then the line draws down over the bars. Put it beside GanttGrid. - `className`: `string`. Classes for the root. The layout reads variables you can set here: --gantt-head-h (2.5rem), --gantt-group-h (2.5rem), --gantt-row-h (2.75rem), --gantt-name-w (12rem, down to 8.5rem in a narrow box), --gantt-day-w (0.625rem, the least width of a day; a wider box stretches the days), and --gantt-bg (the page color, behind the fixed names). ### Accessibility - The chart is a region named by aria-label, around a table: a header row, a row group per group with its title as a row header, and a row per item with its name as the row header. - With onItemOpen, each bar is a button named by its item, its dates, and its progress, like 'Payments page, Oct 19 – Nov 6, 45% done'. Focus scrolls it clear of the fixed names. - Without onItemOpen, each row's cell says the same in hidden text. When the dates scroll, the scroll box is one Tab stop, so a keyboard can scroll them. With buttons inside, it is no stop of its own. - Hover or keyboard focus on a bar shows its name, dates, progress, and caption in a tooltip. One tooltip shows at a time. - A name cut off by the column shows in full in a tooltip on hover, or on a tap when the bars are not buttons. Screen readers read the whole name. - The week lines and the today marker are hidden from screen readers. The header says the range and today's date. - In forced colors, each bar keeps an outline, the done part and the today marker take the text color, the today line widens, and the week lines turn GrayText, so today stays the strongest line. - With reduced motion, bars and the today line fade in place instead of growing. ### Examples #### Items by stage, with today marked ```tsx openItem(id)} /> ``` #### Dates in another locale, with Date values put on their day in a time zone ```tsx ``` #### Your own name column, with the date side from the parts ```tsx

Name

{items.map((item, index) => (

{item.label}

))}

``` ## Glide Highlight > One highlight for a whole list, which glides from row to row on a spring instead of each row lighting on its own. - Name: `glide-highlight` - Status: beta - Categories: motion, display - File: the install writes `glide-highlight.tsx` to your `ui` alias, `@/components/ui` by default. - Gallery: https://txbrendan.dev/components/glide-highlight - Registry item: https://txbrendan.dev/r/glide-highlight.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/glide-highlight ``` ### Use it for - A list, menu, or row of links where the pointer sweeps across many rows. One highlight that glides reads as one motion, where a highlight per row blinks. - Call useGlide with the list's ref and the highlight's ref. Call follow(row, event) from pointerover and pointermove, to(row) from focus or highlight events, and hide() when they end. - follow leans the highlight toward the pointer during a quick sweep, so it crosses rows at an even speed. It settles back onto its row once the pointer rests. - A list that already marks one row, like data-highlighted, needs no hook. Pass that attribute as track, and the highlight follows the marked row by itself. - Give a row data-tone, like danger, and the highlight takes that tone when it arrives there. - Pass instant for moves the keys make, so a held arrow key always shows one row fully lit. - Style each row's text with data-\[lit\]:. A row gets data-lit once the highlight is more than halfway onto it, so text and highlight arrive together. ### Avoid it for - A single control's hover. One button needs no glide. Its own hover fill is enough. - Showing the selected row. The highlight follows the pointer and the keys. Mark the chosen row with its own fill or aria-current. - A list that is not positioned and isolated. The highlight sits behind the rows, so the list needs both, or it measures wrong and hides behind the page. ### Props - `useGlide`: `(listRef: RefObject, highlightRef: RefObject, options?: { axis?: "x" | "y"; span?: "row" | "full" }) => Glide`. Helper. Moves the highlight. axis is "y" for a column and "x" for a row of links. span "row" fits each row, and "full" spans the list's width so it only moves up and down. - `Glide`: `{ follow: (row: HTMLElement, pointer: { clientX: number; clientY: number }) => void; to: (row: HTMLElement, move?: { lead?: number; instant?: boolean }) => void; hide: (options?: { instant?: boolean }) => void; press: (pressed: boolean) => void; row: () => HTMLElement | null }`. Type. follow sends it to the row under the pointer and leans it ahead on a quick sweep. to sends it to a row: it fades in there the first time and glides after that. hide fades it out where it is. press darkens it. row is the row it is on. - `GlideHighlight`: `ComponentProps<"span">`. Part. The highlight. Put it first inside the list, with the same ref, and give it its fill as a class, like bg-foreground/8. - `span`: `"row" | "full"`. Default `"row"`. On GlideHighlight. Match the span you passed useGlide. - `track`: `string`. On GlideHighlight. An attribute that marks one row in its parent at a time, like data-highlighted. The highlight then follows that row with no hook: it glides when the pointer moved the mark and jumps when the keys did. It sets data-glide on the parent, so rows can drop their own fill there. ### Accessibility - The highlight is hidden from screen readers. It only shows where the pointer or the keys are. - It does not take focus or show focus. Keep each row's own focus ring, or draw the ring on the highlight while it sits on the focused row. - Reduced motion, or motion off, makes it jump from row to row instead of gliding. - Forced colors paint its fill away. Give the lit row an outline there, so the highlight still shows. ### Examples #### Glide one highlight down a list as the pointer moves ```tsx import { useRef } from "react"; function GlideList() { const list = useRef(null); const highlight = useRef(null); const glide = useGlide(list, highlight); return (
{ const row = (event.target as Element).closest("button"); if (row) glide.follow(row, event); }} onPointerLeave={() => glide.hide()} > {["Inbox", "Drafts", "Sent"].map((label) => (

))}
); } ``` #### Follow the row a list already marks, with no hook ```tsx
{/* Rows that set data-highlighted on the active one */}
``` #### Jump with no glide when the arrow keys move the highlight ```tsx glide.to(row, { instant: true }); ``` ## Heat Calendar > Weeks across and days down, in one hue whose strength is how much happened, or each day in its event type's color, with a legend that filters and a span you can measure. - Name: `heat-calendar` - Status: beta - Categories: charts - File: the install writes `heat-calendar.tsx` to your `ui` alias, `@/components/ui` by default. - Other registry items: `@txbrendan/chart`, `@txbrendan/motion-timing`, `@txbrendan/rolling-number`. The install adds them. - Gallery: https://txbrendan.dev/components/heat-calendar - Registry item: https://txbrendan.dev/r/heat-calendar.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/heat-calendar ``` ### Use it for - Activity over months, like training attendance, logins, or match minutes, where the pattern matters more than one day. - Pass values as values\[week\]\[day\] from 0 to 1, oldest week first and Monday first, with a title or aria-label. - Pass maxCount and unit, like 8 and 'sessions', so a day reads '4 sessions', not '50%'. - For a club's calendar, pass events: an ISO day to its event or events. Each day takes its type's color. - Pass types to name event types and set their order. Each color defaults to the next chart color. - Pass endDate for the last day shown. Without it the calendar ends today, once the page is in the browser. ### Avoid it for - Exact numbers people must compare. Use BarChart or BreakdownList. - A trend over a few points. Use LineChart or Sparkline. - Booking or choosing a day. Use Calendar. - More than about five event types. The colors stop being easy to tell apart. ### Props - `values`: `number[][]`. Intensity mode. values\[week\]\[day\] from 0 to 1, Monday first. The last row is the week that holds endDate. - `events`: `Record`. Event mode. An ISO day, like '2026-09-26', to its event or events. An event is a type id, like 'training', or { type, label?, opponent?, score? }. A score of \[24, 17\] reads 'Won 24–17 vs Harbour Town'. - `types`: `{ id: string; label: string; color?: string }[]`. Event types in legend order. Default: each type in events as it first appears. A color is a theme token, like 'var(--chart-3)'. - `weeks`: `number`. Default `values.length, or 26`. How many weeks to show. - `maxCount`: `number`. The count a full cell stands for. With 8, a value of 0.5 reads '4 sessions'. - `unit`: `string`. The noun after counts, plural, like 'sessions'. A count of one drops the final s. - `endDate`: `Date | string`. Default `today`. The last day shown, as an ISO day or a Date. One it cannot read falls back to today. Days after it in its week are left blank. - `title`: `ReactNode`. Names the calendar and its grid. Pass this, aria-label, or aria-labelledby. - `locale`: `string`. Default `"en-US"`. The locale for day and month names. The default keeps the server and the browser the same. - `className`: `string`. Extra classes for the figure. '\[--heat-calendar-color:var(--chart-3)\]' sets the one hue in intensity mode. It defaults to --chart-1. ### Accessibility - The days are a role="grid", one row per weekday. Each day is a gridcell named by its date and what happened, like 'Sat, Sep 26: 4 sessions'. - The grid is one Tab stop. Left and Right move a week, Up and Down move a day, and Home and End go to the first and last days. - Enter or Space starts a span, and again ends it. A status line says the span's total. Escape clears it and goes no further. - The legend steps are buttons. Hovering or focusing one shows only its days. Pressing one keeps it on, with aria-pressed. - The readout over a day is hidden from screen readers, since each day already says the same. - In forced colors, the days, the legend swatches, and the readout's dots keep their hues, so each day still matches its legend step or type. Empty days and the None step mix the user's page and text colors, so they stay faint. The level steps and the event colors, including colors set in types, pull toward the text color. So on a light or a dark page, the steps stay in order above None, and event days stand out from the page. Words, outlines, and the focus ring take the user's colors. - With reduced motion, the cells fade in without the spring, and nothing lifts or glides. ### Examples #### Training attendance ```tsx ``` #### A club's calendar by event type ```tsx ``` #### In another hue ```tsx ``` ## Hover Actions > A row's quick icon actions in a small glass toolbar that sits on the row and springs in while the row is hovered or holds focus. A small tooltip above each icon says what it does. - Name: `hover-actions` - Status: beta - Categories: actions - File: the install writes `hover-actions.tsx` to your `ui` alias, `@/components/ui` by default. - Other registry items: `@txbrendan/tool-button`, `@txbrendan/tooltip`. The install adds them. - Gallery: https://txbrendan.dev/components/hover-actions - Registry item: https://txbrendan.dev/r/hover-actions.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/hover-actions ``` ### Use it for - The quick jobs on a list row, like Reply, Edit, Archive, or Move, so people finish them without leaving the page. - Keep two to four actions. Put the rest in a Menu. - Set visible while the row is hovered or holds focus. Focus inside the bar shows it too, so keyboard users always reach it. - Give each action a shortcut, and use RowActions to make the keys work. The tooltip teaches each one. - Use icons. Each icon's tooltip says what it does, so the bar stays small and never covers the row. - Give an action a result when its press changes something, like an archive. The button says what happened, with Undo. - Place it yourself, usually absolute at the row's right edge, inside a row with position: relative. ### Avoid it for - The only way to do something on touch screens. Touch has no hover, so keep the bar visible there, or offer the action in the row's own page. - A row's main action, like opening it. Make the row itself the link or button. - A long bar of actions. Use a Menu for more than four. - Words in a row's bar, like a text Remind button. They crowd the row. Let the tooltip say the word. ### Props - `actions`: `HoverAction[]`. Required. The actions, in order. Pass the same objects to RowActions and ActionKeys, so the key, the tooltip, and the button never drift apart. - `HoverAction`: `{ label: string; icon?: ReactNode; onClick?: () => void | Promise; shortcut?: string; text?: boolean; tone?: "neutral" | "danger"; result?: ActionResult; disabled?: boolean }`. Type. label names the button. shortcut is one key, taught in the tooltip. text shows the label beside the icon. A promise from onClick shows a spinner, and a failure shows Retry. result is ToolButton's ActionResult. - `visible`: `boolean`. Default `true`. Shows the bar. Set it while the row is hovered or holds focus. Hidden, the bar stays in the Tab order, and focus inside shows it. - `aria-label`: `string`. Default `"Actions"`. Names the toolbar. Name the row, like 'Actions for Tom Hale', when a list has many. - `ref`: `Ref`. Reaches the toolbar. ActionKeys takes it as within. - `className`: `string`. Extra classes on the toolbar. Later classes win. ### Accessibility - The bar is a toolbar: one Tab stop, and the arrow keys move between its buttons. - Each button is named by its action's label. The tooltip shows the label and the key to sighted mouse and keyboard users. - A hidden bar is only see-through. It stays in the Tab order and the accessibility tree, and focus inside shows it at once. - A hidden bar ignores the pointer, so a press never lands on a button no one can see. - Results are said once through a polite live region, and each button's name follows its state. ### Examples #### On a list row ```tsx import { Archive, Pencil, Reply } from "lucide-react"; import { useState } from "react"; function PersonRow({ name }: { name: string }) { const [lit, setLit] = useState(false); return (
setLit(true)} onMouseLeave={() => setLit(false)} onFocus={() => setLit(true)} onBlur={(event) => !event.currentTarget.contains(event.relatedTarget) && setLit(false)} > {name} , label: "Reply", shortcut: "R" }, { icon: , label: "Edit", shortcut: "E" }, { icon: , label: "Archive", shortcut: "A", result: { label: "Archived", onUndo: () => {} } }, ]} />
); } ``` ## Hover Card > A peek: hover, focus, or tap a person, status, count, or position to see the story behind it, without leaving the page. - Name: `hover-card` - Status: beta - Categories: overlays - File: the install writes `hover-card.tsx` to your `ui` alias, `@/components/ui` by default. - npm packages: `@base-ui/react`. The install adds them. - Other registry items: `@txbrendan/motion-timing`. The install adds them. - Gallery: https://txbrendan.dev/components/hover-card - Registry item: https://txbrendan.dev/r/hover-card.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/hover-card ``` ### Use it for - Showing the story behind a person, a status, a count, or a position, like who the 21 going are. - Put a PeekCard in content. Its title names the peek, and in a peek it shows a glance: up to 3 facts and 2 actions. - Mark each row of a list with data-peek-row. The peek then opens beside the row, so the rows above and below stay in reach. - Set control when the trigger is itself a control, like an event card you press to select. It keeps its role and its Enter. - Set underline on words in a sentence, so people can see there is more behind them. - While a menu, list, or popover is open, hover opens no peek outside it. The peek waits, and opens once that closes if the pointer is still there. ### Avoid it for - Anything people must see to finish a task. Peeks are extra. Put the rest on the page the peek links to. - A short name for an icon button. Use a Tooltip. - A menu of choices, or a form. Use a Menu, a Popover, or a Dialog. - Opening one on click. A peek opens on hover, focus, and tap. Use a Popover for a click. ### Props - `content`: `ReactNode`. Required. What the peek shows. A PeekCard is the standard content. - `children`: `ReactNode`. The trigger: a person, a status, a count, or a position. - `delay`: `number`. Default `320`. How long the pointer rests on the trigger before the peek opens, in milliseconds. - `glance`: `boolean`. Default `true`. A PeekCard inside shows up to 3 facts and 2 actions. False shows it whole. - `width`: `number`. Default `320`. The peek's width in pixels. It never grows past the screen. - `side`: `"auto" | "right" | "left" | "top" | "bottom"`. Default `"auto"`. auto opens beside a row marked data-peek-row, level with the row, or else below the trigger, lined up with its start. It flips when there is no room. - `inline`: `boolean`. Default `true`. A span trigger that sits in a line of text. False makes it a block. - `control`: `boolean`. Default `false`. The child is itself a control. It keeps its role and its Enter, and the peek follows its hover and focus. - `underline`: `boolean`. Default `false`. A faint dotted underline under the whole trigger, on every line when it wraps. - `label`: `string`. The peek's name for screen readers, when its content is not a PeekCard with a title. - `open`: `boolean`. Controlled. The peek shows while true. Hover, focus, Esc, and a press outside only ask, through onOpenChange. - `defaultOpen`: `boolean`. Default `false`. Starts open, without taking focus. - `onOpenChange`: `(open: boolean) => void`. Hears every open and close, or what the peek asks for when controlled. - `effect`: `"rise" | "grow"`. Default `"rise"`. How the peek opens and closes. rise fades in and moves out from the trigger. grow fades in and grows from the trigger, and closes the same way. Left out, it follows an effect-\ class on \, where popups open, and rises with none. - `className`: `string`. Extra classes on the trigger. Later classes win. - `useHoverCard`: `() => { titleId; registerTitle; glance; close } | null`. Hook. Content inside a peek reads it to name the peek, to trim to a glance, and to close it. ### Accessibility - The trigger is a focusable role="button" with aria-haspopup="dialog", aria-expanded, and aria-controls while open. With control, the child keeps its own role instead. - The peek opens on keyboard focus at once, and on hover after the delay. A tap opens it on touch, and a second tap on the trigger closes it. - The peek is a non-modal role="dialog". A PeekCard's title names it. Without one, label names it, or else the trigger's words. - Enter or Space on the trigger moves focus into the peek. Tab moves through it, and past either end focus is back on the trigger. Esc closes it and puts focus back. - ↑ and ↓ step to the peek above or below, while the keyboard is on a trigger or in its peek. - A trigger with no words, like an icon or a swatch, needs an aria-label. The console says so until it has one. - It opens with a quick fade from its trigger's side, and closes with a quicker fade and a slight shrink. ### Examples #### Words in a sentence ```tsx
Design review on Tuesday:{" "} Sam, Kate, Josh, and 18 more.
}> 21 going
``` #### Rows in a list ```tsx const people = [ { name: "Sam Carter", role: "Design lead" }, { name: "Kate Clarke", role: "Support lead" }, ];
{people.map((person) => (
{person.role}
}> {person.name}
))}
``` #### Around a control ```tsx Starts 15:00 in the Boardroom.
}> ``` #### Grows from its trigger ```tsx
Design review on Tuesday:{" "} Sam, Kate, Josh, and 18 more.
}> 21 going
``` ## Hub Link > A place to go: a spot icon or an icon, a title, and a line under it, washed on hover. - Name: `hub-link` - Status: beta - Categories: navigation - File: the install writes `hub-link.tsx` to your `ui` alias, `@/components/ui` by default. - Other registry items: `@txbrendan/spot-icon`. The install adds them. - Gallery: https://txbrendan.dev/components/hub-link - Registry item: https://txbrendan.dev/r/hub-link.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/hub-link ``` ### Use it for - The links on a hub or home page: Calendar, People, Payments, each with a line saying what is there. - Use spot when the link names a place to go. Use icon, in iconTone, for a quieter list. - Use tone when the line under the title says something needs you, like "Due today" in warning. - The wash hangs 10px past each side, so the icon and words keep the column's edge. Leave the column that room. - Pass href for a link. Without it, the hub link is a button, for onClick. ### Avoid it for - A row in a list. Use ListRow. - A call to action. Use Button. - Color alone for something that needs you. The line must say it in words. ### Props - `title`: `string`. Required. Where it goes, like "Calendar". - `description`: `string`. The line under the title. - `spot`: `ReactNode`. The icon for a 32px SpotIcon. It takes the place of icon. - `icon`: `ReactNode`. A plain 20px icon, in iconTone. - `iconTone`: `"neutral" | "brand" | "danger" | "success" | "warning"`. Default `"brand"`. The plain icon's color role. A spot is always the brand's. - `tone`: `"neutral" | "brand" | "danger" | "success" | "warning"`. Default `"neutral"`. Colors the description. neutral is muted. - `href`: `string`. Makes it a link. Without it, it is a button. - `onClick`: `(event) => void`. Runs on press. - `className`: `string`. Extra classes on the link. Later classes win. ### Accessibility - A link with href, and a button without it, named by its title and description. - The spot and the icon are hidden from screen readers, since the title names the place. - A toned description keeps its words, so color is never the only signal. - The focus ring goes around the whole wash. ### Examples #### Two links, one with a warning ```tsx import { CalendarDays, CreditCard } from "lucide-react";
} title="Calendar" description="Next: Sat 3 Oct · Demo day" href="/calendar" /> } title="Payments" description="Due today" tone="warning" href="/payments" />
``` ## Icon Color Picker > Choose an artwork color with a native picker or hex field, with validation and a reset. - Name: `icon-color-picker` - Status: beta - Categories: forms - File: the install writes `icon-color-picker.tsx` to your `ui` alias, `@/components/ui` by default. - Other registry items: `@txbrendan/input`, `@txbrendan/button`. The install adds them. - Gallery: https://txbrendan.dev/components/icon-color-picker - Registry item: https://txbrendan.dev/r/icon-color-picker.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/icon-color-picker ``` ### Use it for - Controlled color editing for icon artwork. Use null to retain the original color. - Accepts three- or six-digit hex. Invalid input preserves the last valid value. ### Avoid it for - Replacing the interface theme. Use theme tokens for controls and text. ### Props - `original`: `string`. Original hex used for the default swatch and placeholder. - `value`: `string | null`. Chosen hex color, or null for the original. - `onValueChange`: `(value: string | null) => void`. Called for valid colors and resets. - `label`: `string`. Default `"Icon color"`. Visible label and accessible name. - `resetLabel`: `string`. Default `"Use default color"`. Reset action label. - `disabled`: `boolean`. Default `false`. Disables editing. ### Accessibility - Both inputs are labeled. Invalid hex has an associated message and aria-invalid. - Chosen artwork colors are not contrast-checked. Controls retain theme colors. ### Examples #### Controlled artwork ```tsx ``` ## Icon > A Lucide icon by name, from a small fixed set, sized at 14, 16, or 20px and colored by the text color. - Name: `icon` - Status: beta - Categories: media, display - File: the install writes `icon.tsx` to your `ui` alias, `@/components/ui` by default. - npm packages: `lucide-react`. The install adds them. - Gallery: https://txbrendan.dev/components/icon - Registry item: https://txbrendan.dev/r/icon.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/icon ``` ### Use it for - Drawing an icon from data, like a name stored with a menu item or a list row. - Use size sm in compact rows, md by default, and lg in hub rows. - Set the color with a text token class, like text-muted-foreground or text-primary. - Pass title when the icon stands alone and means something. Leave it off when text beside it says the same thing. ### Avoid it for - Icons you write in code. Import them from lucide-react, like \. Other parts take icons as elements. - Names outside the set. They draw an empty box and warn once. Import that icon from lucide-react instead. - Content spots, like a feature list, an empty state, or a card's header. Use SpotIcon. - Raw colors. Use a text token class, so the icon follows the theme. ### Props - `name`: `IconName`. A kebab-case Lucide name from the set: arrow-right, bell, calendar, camera, check, chevron-down, chevron-right, circle-alert, clock, credit-card, download, external-link, eye, file-text, flag, heart, house, image, info, link, lock, mail, map-pin, medal, megaphone, message-circle, minus, pencil, phone, plus, search, settings, share, shield, shirt, star, ticket, trash-2, triangle-alert, trophy, upload, user, users, x. iconNames lists them. - `size`: `"sm" | "md" | "lg"`. Default `"md"`. sm is 14px, md is 16px, lg is 20px. - `strokeWidth`: `number`. Default `2`. Line width. lg draws 1.75 unless you set it. - `title`: `string`. Names the icon for screen readers. Without it the icon is hidden from them. - `className`: `string`. Extra classes. Set the color here, like text-muted-foreground. Later classes win. ### Accessibility - Without title the icon has aria-hidden, so text beside it is all a screen reader hears. - With title it is role="img" with that name. Use it only when the icon stands alone. - An icon inside a button does not name the button. Give an icon-only button its own aria-label. - It takes the text color, so a text token's contrast covers it. ### Examples #### An icon beside text ```tsx
Tuesday 6 October
``` #### Sizes ```tsx

``` #### An icon from data, with a name ```tsx const status = { icon: "triangle-alert", label: "Sign-in errors" } as const; ``` ## Inline Edit > A value people change where it sits. The value is the button, and the field opens in its exact box. - Name: `inline-edit` - Status: beta - Categories: forms - File: the install writes `inline-edit.tsx` to your `ui` alias, `@/components/ui` by default. - Gallery: https://txbrendan.dev/components/inline-edit - Registry item: https://txbrendan.dev/r/inline-edit.json ### Install 1. Add the registry to `components.json`. Do this first, once: ```bash npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json" ``` The command writes this entry. You can also add it by hand: ```json { "registries": { "@txbrendan": "https://txbrendan.dev/r/{name}.json" } } ``` Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control. 2. Add the theme once per app. It replaces your color tokens with ones checked for contrast: ```bash npx shadcn@latest add @txbrendan/theme ``` 3. Add the component: ```bash npx shadcn@latest add @txbrendan/inline-edit ``` ### Use it for - One short value on a page or a row that people change now and then: a name, a title, a place, a number. - Pass label as a short noun, like "location". It names the value "Edit location" and the empty state "Add location". - Save in onSave. Return the promise from your request, and the change shows at once, says Saving…, and comes back if it fails. - When you control value, set it to the new text before your promise resolves. ### Avoid it for - Text that runs to several lines, like a description. Use a Textarea in a form or a dialog. - Values that must change together, like a start and an end date. Edit them in one form with one Save. - A form people fill in once from top to bottom. Use Input with a label. - Adding a pencil or an Edit button beside the value. The value is already the button. ### Props - `label`: `string`. What the value is, as a short noun. Required. It names the value and the empty state. - `value`: `string`. The saved value. Controlled. Set it to the new text before your onSave promise resolves. - `defaultValue`: `string`. Default `""`. The saved value, when you do not control value. - `onSave`: `(value: string) => void | Promise`. Called with the trimmed new text when it changed. Enter saves, and so does clicking away. Escape cancels. A promise shows Saving… until it settles. A rejection or a throw puts the old value back and shows errorText. The newest save wins. - `size`: `"sm" | "md" | "lg"`. Default `"md"`. Text size: 11, 13, or 16px. The box is as tall as a small control, so density scales it. - `disabled`: `boolean`. Default `false`. Shows the value as plain text. It is not a button and cannot be edited. - `placeholder`: `string`. Shown in the empty field while editing. - `editText`: `string`. Default `"Edit {label}"`. Words before the value in its name for screen readers. Set it to translate. - `addText`: `string`. Default `"Add {label}"`. Shown with a plus when the value is empty. Set it to translate. - `savingText`: `string`. Default `"Saving…"`. Shown after the value while its save runs. - `errorText`: `string`. Default `"Could not save. Try again."`. Shown under the value when a save fails. - `className`: `string`. Extra classes on the outer span. Later classes win, so className='text-base' replaces the size. ### Accessibility - The value is a native \

Billing

by default. Use render={\

Overview

Details

Getting started

Next steps

Usage

or \

or \

or \