` element. > [!NOTE] > > A `ProgressBar` is announced with an `aria-label` of `"Progress"` by default. Pass your own `aria-label` when a page renders more than one, so that each is announced with what it is tracking. ## Examples ### Basic usage Render a `ProgressBar` by giving it a numeric `value` prop from `0` to `100`: ```tsx demo import { ProgressBar } from "@tenstorrent/vesper/progress-bar"; export default function BasicProgressBar() { return ; } ``` ### Different sizes A `ProgressBar` can be rendered in one of three sizes, `"sm"`, `"md"`, or `"lg"`. The default size is `"md"`: ```tsx demo import { ProgressBar } from "@tenstorrent/vesper/progress-bar"; export default function ProgressBarSizes() { return (

); } ``` ### Rendering step intervals A `ProgressBar` can be rendered in one of two variants, `"default"` or `"steps"`. The default variant is `"default"`, which renders a `ProgressBar` with no step intervals. To render a `ProgressBar` with step intervals, use the `"steps"` variant: ```tsx demo import { ProgressBar } from "@tenstorrent/vesper/progress-bar"; export default function SteppedProgressBar() { return ; } ``` A `"steps"` variant `ProgressBar` will visually snap the progress indicator to the nearest interval, using `Math.round` by default. To adjust how step-rounding is calculated, you can pass a custom rounding function to the component via the `stepRoundingStrategy` prop: ```tsx demo import { ProgressBar } from "@tenstorrent/vesper/progress-bar"; export default function StepRoundingStrategies() { return (

{/* rounds with `Math.ceil` instead of `Math.round` */} {/* rounds with `Math.floor` instead of `Math.round` */}

); } ``` By default, when rendering a stepped `ProgressBar`, it will render with `10` steps. To modify the number of steps rendered, pass any positive integer value to the `steps` prop: ```tsx demo import { ProgressBar } from "@tenstorrent/vesper/progress-bar"; export default function FiveStepProgressBar() { return ; } ``` ### Animating progress To animate a `ProgressBar` as its `value` changes, you can pass `animated={true}` or just `animated` as a prop: ```tsx demo import { useState } from "react"; import { Button } from "@tenstorrent/vesper/button"; import { ProgressBar } from "@tenstorrent/vesper/progress-bar"; import { Typography } from "@tenstorrent/vesper/typography"; export default function AnimatedProgressBars() { const [value, setValue] = useState(66); return (

Current value: {value}

); } ``` --- Source: https://vesper.tenstorrent.com/components/radio-group.md # Radio Group A group of mutually exclusive radio inputs with labels. Supports horizontal and vertical layouts, controlled and uncontrolled modes, and individual option disabling. ```tsx demo import { RadioGroup } from "@tenstorrent/vesper/radio-group"; export default function RadioGroupDemo() { return ( ); } ``` ## Options | Prop | Type | Description | Default | | -------------- | ---------------------------- | ----------------------------------------------------------------------------------- | ------------ | | `name` | `string` | The name attribute shared by all radio inputs, used for form submission. | — | | `options` | `RadioGroupItem[]` | The list of radio options. Each has `value`, `label`, optional `disabled` and `id`. | — | | `size` | `"sm" \| "md"` | The size of the radio inputs and labels. | `"md"` | | `orientation` | `"horizontal" \| "vertical"` | The layout direction of the radio options. | `"vertical"` | | `value` | `string` | The currently selected value (controlled mode). | — | | `defaultValue` | `string` | The initially selected value (uncontrolled mode). | — | | `onChange` | `(value: string) => void` | Callback fired when the selected value changes. | — | | `required` | `boolean` | When `true`, a selection is required for form validation. | `false` | | `disabled` | `boolean` | When `true`, disables all options. | `false` | All other props are forwarded to the wrapping `

` element. ### `RadioGroupItem` options | Property | Type | Description | | ---------- | --------- | ---------------------------------------------------------------------------------------- | | `value` | `string` | The value submitted with form data and passed to `onChange`. Must be unique. | | `label` | `string` | The text displayed next to the radio input. | | `disabled` | `boolean` | When `true`, prevents this individual option from being selected. Defaults to `false`. | | `id` | `string` | An `id` applied to this option's ``, used to reference it from validation errors. | Use a `RadioGroup` when exactly one option out of many must be chosen. Reach for [the `Choicebox` component](https://vesper.tenstorrent.com/components/choicebox.md) when each option needs a description or a card-style target, [the `Toggle` component](https://vesper.tenstorrent.com/components/toggle.md) when a compact segmented control fits better, or [the `Select` component](https://vesper.tenstorrent.com/components/select.md) when the list is long enough that it should collapse into a dropdown. ## Examples ### Defining options Each entry in the `options` array describes a single radio input. `value` is what gets submitted and reported to `onChange`, while `label` is the text rendered beside the input: ```tsx demo import { RadioGroup } from "@tenstorrent/vesper/radio-group"; export default function BasicRadioGroup() { return ( ); } ``` Options are rendered in the order they are provided, and they all share the `name` you pass to the group, which is what makes the selection mutually exclusive. ### Uncontrolled vs controlled Render a `RadioGroup` in an uncontrolled fashion to let it keep track of its own selection. Pass `defaultValue` if one of the options should be selected initially: ```tsx demo import { RadioGroup } from "@tenstorrent/vesper/radio-group"; export default function UncontrolledRadioGroup() { return ( ); } ``` If you need to control which option is selected, you can do so via the `value` and `onChange` props. `onChange` receives the newly selected value directly: ```tsx demo import { useState } from "react"; import { RadioGroup } from "@tenstorrent/vesper/radio-group"; import { Typography } from "@tenstorrent/vesper/typography"; export default function ControlledRadioGroup() { const [value, setValue] = useState("md"); return (

Selected value: {value}

); } ``` ### Orientation Options are stacked vertically by default. Pass `orientation="horizontal"` to lay them out in a row, which suits short labels and small option sets: ```tsx demo import { RadioGroup } from "@tenstorrent/vesper/radio-group"; export default function HorizontalRadioGroup() { return ( ); } ``` ### Different sizes A `RadioGroup` can be rendered at `sm` or `md` size, defaulting to `md`. Size affects the dimensions of the radio inputs as well as the text styles of their labels: ```tsx demo import { RadioGroup } from "@tenstorrent/vesper/radio-group"; export default function RadioGroupSizes() { return (

); } ``` ### Disabling options Pass `disabled` to an individual option to prevent it from being selected while leaving the rest of the group interactive: ```tsx demo import { RadioGroup } from "@tenstorrent/vesper/radio-group"; export default function RadioGroupWithDisabledOption() { return ( ); } ``` Passing `disabled` to the group itself disables every option at once, which is useful while a form is submitting: ```tsx demo import { RadioGroup } from "@tenstorrent/vesper/radio-group"; export default function DisabledRadioGroup() { return ( ); } ``` ### Usage in forms `RadioGroup` renders native `` elements inside a `

`, so it works with regular form submission and native validation. The selected option submits its `value` under the group's `name`, and passing `required` refuses submission until one of the options is picked: ```tsx demo import { useState } from "react"; import { Button } from "@tenstorrent/vesper/button"; import { RadioGroup } from "@tenstorrent/vesper/radio-group"; import { Typography } from "@tenstorrent/vesper/typography"; export default function FormRadioGroupDemo() { const [submitted, setSubmitted] = useState(null); return ( { event.preventDefault(); const data = new FormData(event.currentTarget); setSubmitted(String(data.get("contact") ?? "")); }} > {submitted !== null && ( Submitted value: contact={submitted} )} ); } ``` > [!NOTE] > > Give the group an accessible name so assistive technology can announce what the options belong to. `RadioGroup` renders a `

`, so you can either pass it an `aria-label`, or point `aria-labelledby` at the heading or label that already names the group. --- Source: https://vesper.tenstorrent.com/components/range.md # Range A multi-thumb range input for selecting a span of numeric values between a minimum and maximum. It supports tick marks, value labels, and configurable stepping. ```tsx demo import { Range } from "@tenstorrent/vesper/range"; export default function RangeDemo() { return ( ); } ``` ## Options | Prop | Type | Description | Default | | ----------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------ | | `thumbAriaLabels` | `string[]` | Accessible `aria-label` attributes for each thumb, in the same order as the values. Required. | — | | `values` | `number[]` | The values of each thumb (controlled mode). The number of thumbs matches the length of this array. | — | | `defaultValues` | `number[]` | The initial thumb values (uncontrolled mode). | `[min, max]` | | `onValuesChange` | `(values: number[]) => void` | Callback fired as thumb values change during interaction. Receives the full array of current values. | — | | `onValuesCommit` | `(values: number[]) => void` | Callback fired when a thumb interaction is completed, eg. on pointer up. Receives the final array of values. | — | | `min` | `number` | The minimum allowed value. | `0` | | `max` | `number` | The maximum allowed value. | `100` | | `step` | `number` | The stepping interval between selectable values. | `1` | | `minStepsBetweenThumbs` | `number` | The minimum number of steps required between thumbs, preventing them from overlapping. | `1` | | `showTicks` | `boolean` | When `true`, renders tick marks along the track at each step interval. | `false` | | `showValueLabels` | `boolean` | When `true`, displays a value label above each thumb. | `false` | | `valueLabels` | `string[]` | Custom display labels for each thumb. When unset, each label falls back to that thumb's current value. | — | | `disabled` | `boolean` | When `true`, prevents interaction. | `false` | | `name` | `string` | The form field name submitted with form data. Every thumb submits its value under this name. | — | | `form` | `string` | Associates the range with a `

` element by its `id`. | — | All other props are forwarded to the wrapping `

` element. If you only need to select a single value, reach for [the `Slider` component](https://vesper.tenstorrent.com/components/slider.md) instead: it renders the same track, ticks, and labels, but exposes a single-value API. ## Examples ### Uncontrolled vs controlled Render a `Range` in an uncontrolled fashion to let it keep track of its own values. Pass `defaultValues` if the thumbs should start somewhere other than `min` and `max`: ```tsx demo import { Range } from "@tenstorrent/vesper/range"; export default function UncontrolledRange() { return ( ); } ``` If you need to control the values, use the `values` and `onValuesChange` props. `onValuesChange` fires continuously as a thumb is dragged, and always receives the full array of values: ```tsx demo import { useState } from "react"; import { Button } from "@tenstorrent/vesper/button"; import { Range } from "@tenstorrent/vesper/range"; import { Typography } from "@tenstorrent/vesper/typography"; export default function ControlledRange() { const [price, setPrice] = useState([25, 75]); return (

Selected values: {price.join(", ")}

); } ``` Use `onValuesCommit` when you only care about the final values of an interaction, eg. to avoid firing a request on every pointer move: ```tsx import { Range } from "@tenstorrent/vesper/range"; export default function PriceRange() { return ( fetchResults({ min, max })} thumbAriaLabels={["Price (min)", "Price (max)"]} /> ); } ``` ### Bounds and stepping `min`, `max`, and `step` describe the values a thumb can take, defaulting to `0`, `100`, and `1`. A `step` of `50` on a range of `0-1000` restricts thumbs to multiples of 50: ```tsx demo import { Range } from "@tenstorrent/vesper/range"; export default function LargeStepRange() { return ( ); } ``` The `step` also determines how far a thumb moves per arrow key press when it is focused. ### Keeping thumbs apart By default, thumbs must stay at least one step apart. Raise `minStepsBetweenThumbs` when a range needs a wider minimum span. The range below keeps its thumbs at least 20 apart: ```tsx demo import { Range } from "@tenstorrent/vesper/range"; export default function CustomStepBetweenThumbsRange() { return ( ); } ``` The value is measured in steps, not in units, so a `minStepsBetweenThumbs` of `2` on a range with a `step` of `5` keeps thumbs at least 10 apart. ### Showing ticks Pass `showTicks` to mark each step along the track. Ticks are rendered between `min` and `max`, so a range of `0-10` with a `step` of `1` renders nine of them: ```tsx demo import { Range } from "@tenstorrent/vesper/range"; export default function RangeWithTicks() { return ( ); } ``` > [!NOTE] > > Ticks are drawn per step, so a fine `step` on a wide range produces a dense, noisy track. Ticks work best when the range has a handful of stops, eg. a range of `0-100` with a `step` of `10`. ### Value labels Pass `showValueLabels` to render each thumb's current value above it as you drag: ```tsx demo import { Range } from "@tenstorrent/vesper/range"; export default function RangeShowingValueLabels() { return ( ); } ``` Use `valueLabels` to display something other than the raw value, such as a formatted or unit-suffixed one. Labels are matched to thumbs by index, and are only rendered when `showValueLabels` is also passed: ```tsx demo import { useState } from "react"; import { Range } from "@tenstorrent/vesper/range"; export default function CustomThumbLabelsRange() { const [price, setPrice] = useState([30, 70]); return ( `$${value}`)} thumbAriaLabels={["Price (min)", "Price (max)"]} /> ); } ``` > [!IMPORTANT] > > Value labels are presentational, and are not announced by assistive technology. > > Screen readers announce the underlying numeric value of a thumb instead. If a label carries meaning that the number alone doesn't, such as a currency or a unit, include it in the `thumbAriaLabels` too. ### More than two thumbs A `Range` renders one thumb per entry in `values` or `defaultValues`, so it isn't limited to two. Give every thumb an entry in `thumbAriaLabels`, and in `valueLabels` when you are customising labels: ```tsx demo import { Range } from "@tenstorrent/vesper/range"; export default function ThreeThumbsRange() { return ( ); } ``` ### Labels and accessible names `thumbAriaLabels` names the individual thumbs. It is required, and each thumb needs its own entry. A thumb without a label is announced with no indication of which end of the range it controls. ```tsx demo import { Range } from "@tenstorrent/vesper/range"; export default function RangeDemo() { return ( ); } ``` ### Keyboard interaction Each thumb is a native ``, so a `Range` is fully keyboard operable once a thumb is focused: | Key | Behaviour | | ------------------------- | -------------------------------------------------------------------- | | `ArrowRight` / `ArrowUp` | Increases the focused thumb by `step`. | | `ArrowLeft` / `ArrowDown` | Decreases the focused thumb by `step`. | | `Shift` + any arrow key | Moves the focused thumb by 10 units instead of `step`. | | `PageUp` / `PageDown` | Increases / decreases the focused thumb by 10 units. | | `Home` | Moves the focused thumb as far towards `min` as it is allowed to go. | | `End` | Moves the focused thumb as far towards `max` as it is allowed to go. | ### Disabling the range Pass `disabled` to prevent all interaction. A disabled `Range` still displays its current values, but its thumbs are skipped in the tab order and excluded from form data: ```tsx demo import { Range } from "@tenstorrent/vesper/range"; export default function DisabledRange() { return ( ); } ``` ### Usage in forms Each thumb renders a native ``, so passing a `name` includes every thumb's value in form submissions under that name. Since every thumb submits under the same `name`, the form below submits `price=20&price=80`. Read both values with `FormData.getAll`: ```tsx const data = new FormData(form); data.getAll("price"); // ["20", "80"] ``` ```tsx demo import { useState } from "react"; import { Button } from "@tenstorrent/vesper/button"; import { Range } from "@tenstorrent/vesper/range"; import { Typography } from "@tenstorrent/vesper/typography"; export default function FormRangeDemo() { const [submitted, setSubmitted] = useState(null); return ( { event.preventDefault(); const data = new FormData(event.currentTarget); setSubmitted(data.getAll("price").map(String)); }} > {submitted !== null && ( Submitted values: {submitted.join(", ")} )} ); } ``` --- Source: https://vesper.tenstorrent.com/components/select.md # Select A form-ready dropdown select component supporting controlled and uncontrolled usage with four visual variants. ```tsx demo import { Select } from "@tenstorrent/vesper/select"; export default function SelectDemo() { return ( ` element that holds the selected value. All other props are forwarded to the underlying `

); } ``` ### Different sizes The `Select` component can be rendered at `sm`, `md`, or `lg` size, defaulting to `md`. Size affects the height, padding, and text styles of the trigger, as well as the size of its icons. ```tsx demo import { Select } from "@tenstorrent/vesper/select"; const COUNTRIES = [ { label: "Canada", value: "ca" }, { label: "Japan", value: "jp" }, { label: "Norway", value: "no" }, ]; export default function SelectSizes() { return (

} placeholder="Select a region" options={[ { label: "United States", value: "us" }, { label: "Europe", value: "eu" }, { label: "Asia Pacific", value: "ap" }, ]} /> ); } ``` > [!NOTE] > > The trailing caret is rendered by the component itself, and flips between its open and closed states as the dropdown is toggled. Only the leading icon is configurable. ### Disabling the select Pass `disabled` to prevent all interaction with the trigger and its dropdown. A disabled `Select` still displays its current selection, but is skipped in the tab order and excluded from form data: ```tsx import { Select } from "@tenstorrent/vesper/select"; export default function DisabledSelect() { return ( {submitted !== null && ( Submitted value: {submitted} )} ); } ``` The value submitted is the `value` of the selected option, not the `label` displayed in the trigger. The form above submits `fruit=apple` when "Apple" is selected. ### Accessing the underlying element Use the `ref` prop when you need direct access to the underlying trigger ` {submitted !== null && ( Submitted value: {submitted} )} ); } ``` A range input always has a value, so a `Slider` submits its current value even if the user never touches it. The form above submits `volume=50` on an untouched slider. --- Source: https://vesper.tenstorrent.com/components/snippet.md # Snippet A compact code display component with a built-in copy-to-clipboard button. Ideal for displaying short commands, installation instructions, or single-line code snippets. ```tsx demo import { Snippet } from "@tenstorrent/vesper/snippet"; export default function SnippetDemo() { return yarn add @tenstorrent/vesper; } ``` ## Options | Prop | Type | Description | Default | | ---------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------- | | `children` | `string` | The code snippet text to display. Also used as the value copied to the clipboard when the copy button is clicked. | — | | `variant` | `"default" \| "contrast"` | The visual style variant of the snippet. | `"default"` | Any additional props are forwarded to the underlying `

` element. ## Examples ### Basic usage Render a `Snippet` by wrapping string children with it: ```tsx demo import { Snippet } from "@tenstorrent/vesper/snippet"; export default function BasicSnippet() { return yarn add @tenstorrent/vesper; } ``` ### Variants A `Snippet` can be rendered in one of two variants: `"default"` or `"contrast"`. Use the `"contrast"` variant to render a `Snippet` with increased contrast: ```tsx demo import { Snippet } from "@tenstorrent/vesper/snippet"; export default function SnippetVariants() { return (

curl https://api.example.com/data curl https://api.example.com/data

); } ``` ### Multiline snippets `Snippet` preserves newlines in the content it renders, so you can also pass string with line breaks to render multiline snippets. You can use escaped newline characters with `\n`: ```tsx demo import { Snippet } from "@tenstorrent/vesper/snippet"; export default function MultilineSnippet() { return {"nvm use 24\nnode -v >> .nvmrc"}; } ``` You can also use template literals: ```tsx demo import { Snippet } from "@tenstorrent/vesper/snippet"; const INSTALL_COMMAND = `nvm use 24 node -v >> .nvmrc`; export default function TemplateLiteralSnippet() { return {INSTALL_COMMAND}; } ``` --- Source: https://vesper.tenstorrent.com/components/split-button.md # Split Button A compound button that combines a primary action button with a dropdown menu toggle. The primary button fires an action, while the secondary caret button opens a menu of alternative actions. ```tsx demo import { SplitButton } from "@tenstorrent/vesper/split-button"; export default function SplitButtonDemo() { return ( {} }, { text: "Save and publish", onSelect: () => {} }, ]} > Save ); } ``` > [!IMPORTANT] > > Keep the content of the action button short (1-3 words) and descriptive of the action being taken, the same way you would for [a `Button`](https://vesper.tenstorrent.com/components/button.md). The menu items beside it should be variations on that action, not unrelated ones. ## Options | Prop | Type | Description | Default | | --------------------- | ---------------------------------------- | --------------------------------------------------------------------------- | --------------- | | `children` | `ReactNode` | The content of the primary action button. | — | | `menuItems` | `MenuItemProps[]` | The list of menu items rendered in the dropdown. **Required.** | — | | `onClick` | `MouseEventHandler` | Callback fired when the primary action button is clicked. | — | | `size` | `"sm" \| "md" \| "lg"` | The size of both the action button and the menu toggle. | `"md"` | | `variant` | `"subtle" \| "contrast"` | The visual style variant applied to both buttons. | `"subtle"` | | `disabled` | `boolean` | When `true`, disables both buttons. | `false` | | `menuButtonAriaLabel` | `string` | An accessible `aria-label` for the menu toggle button. | `"Toggle menu"` | | `menuWidth` | `number` | The width of the dropdown menu in pixels. Scales with the base rem size. | `200` | | `menuSide` | `"top" \| "bottom" \| "left" \| "right"` | The preferred side of the split button to render the dropdown menu against. | `"bottom"` | | `menuSideOffset` | `number` | The distance in pixels from the split button to the dropdown menu. | `8` | | `menuAlign` | `"start" \| "center" \| "end"` | The alignment of the dropdown menu relative to the split button. | `"start"` | | `menuAlignOffset` | `number` | An offset in pixels from the aligned edge of the split button. | `0` | | `menuOpen` | `boolean` | Controls the open state of the dropdown menu (controlled mode). | — | | `defaultMenuOpen` | `boolean` | Whether the dropdown menu is open by default (uncontrolled mode). | `false` | | `onMenuOpenChange` | `(open: boolean) => void` | Callback fired when the dropdown menu's open state changes. | — | All other props are forwarded to the underlying `

` element that wraps the two buttons. Use a `SplitButton` when one action is the obvious default, but closely related variations of it should stay within reach. When there is no default action to promote, reach for [the `Menu` component](https://vesper.tenstorrent.com/components/menu.md) on its own; when there are no alternatives to offer, reach for [the `Button` component](https://vesper.tenstorrent.com/components/button.md). ## Examples ### Basic usage Render a `SplitButton` by giving it some children to label the action button, an `onClick` handler for that action, and the `menuItems` that make up its dropdown: ```tsx demo import { useState } from "react"; import { SplitButton } from "@tenstorrent/vesper/split-button"; import { Typography } from "@tenstorrent/vesper/typography"; export default function BasicSplitButton() { const [lastAction, setLastAction] = useState(null); return (

setLastAction("Save")} menuItems={[ { text: "Save as draft", onSelect: () => setLastAction("Draft") }, { text: "Save and publish", onSelect: () => setLastAction("Publish"), }, ]} > Save Last action: {lastAction ?? "none"}

); } ``` Clicking the action button fires `onClick` without ever opening the menu, and clicking the caret button opens the menu without firing `onClick`. ### Menu items `menuItems` takes the same items as [the `Menu` component](https://vesper.tenstorrent.com/components/menu.md), so each one can render an `icon`, a `description`, and one of the `"default"`, `"selected"`, `"danger"`, `"locked"`, or `"disabled"` styles: ```tsx demo import { Copy, Download, Trash } from "@tenstorrent/vesper/icons"; import { SplitButton } from "@tenstorrent/vesper/split-button"; export default function SplitButtonMenuItems() { return ( {}} menuItems={[ { text: "Export as CSV", icon: , description: "Includes every visible column", onSelect: () => {}, }, { text: "Copy to clipboard", icon: , onSelect: () => {}, }, { text: "Delete export", icon: , style: "danger", onSelect: () => {}, }, ]} > Export ); } ``` ### Variants A `SplitButton` can be rendered in one of two variants, which is applied to both of its buttons at once: | Variant | When to use | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | | `"contrast"` | Use when the action needs strong visual contrast against its surrounding content, such as the main action of a toolbar. | | `"subtle"` | Default variant. Use when the action should sit alongside surrounding content without dominating it, such as a row-level action in a table. | ```tsx demo import { SplitButton } from "@tenstorrent/vesper/split-button"; const MENU_ITEMS = [ { text: "Save as draft", onSelect: () => {} }, { text: "Save and publish", onSelect: () => {} }, ]; export default function SplitButtonVariants() { return (

Contrast Subtle

); } ``` ### Different sizes A `SplitButton` can be rendered in one of three sizes; `"sm"`, `"md"`, or `"lg"`. The default size is `"md"`. ```tsx demo import { SplitButton } from "@tenstorrent/vesper/split-button"; const MENU_ITEMS = [ { text: "Save as draft", onSelect: () => {} }, { text: "Save and publish", onSelect: () => {} }, ]; export default function SplitButtonSizes() { return (

Small Medium Large

); } ``` ### Setting the menu width The dropdown is `200px` wide by default. Pass `menuWidth` when that is too narrow for its items, such as when they carry descriptions or unusually long labels. Like the menu offsets, this value scales with the base rem size: ```tsx demo import { SplitButton } from "@tenstorrent/vesper/split-button"; const MENU_ITEMS = [ { text: "Export as CSV", onSelect: () => {} }, { text: "Export as JSON", onSelect: () => {} }, ]; export default function SplitButtonMenuWidth() { return ( 320px width menu ); } ``` ### Positioning the menu The dropdown is positioned against the split button as a whole, not just the caret button that opens it, so a menu aligned to `"end"` lines up with the right edge of the action button. The `menuSide`, `menuSideOffset`, `menuAlign`, and `menuAlignOffset` props map onto [the `Menu` component](https://vesper.tenstorrent.com/components/menu.md)'s `side`, `sideOffset`, `align`, and `alignOffset` props: ```tsx demo import { SplitButton } from "@tenstorrent/vesper/split-button"; const MENU_ITEMS = [ { text: "Save as draft", onSelect: () => {} }, { text: "Save and publish", onSelect: () => {} }, ]; export default function SplitButtonMenuPlacement() { return (

Aligned to start Aligned to end Above the button

); } ``` ### Controlling the menu's open state By default, a `SplitButton` tracks its own menu state. Pass `defaultMenuOpen` to render with the menu already open, or use `menuOpen` and `onMenuOpenChange` together to own the state yourself: ```tsx demo import { useState } from "react"; import { SplitButton } from "@tenstorrent/vesper/split-button"; import { Typography } from "@tenstorrent/vesper/typography"; export default function ControlledSplitButtonMenu() { const [menuOpen, setMenuOpen] = useState(false); return (

{}} menuItems={[ { text: "Save as draft", onSelect: () => {} }, { text: "Save and publish", onSelect: () => {} }, ]} > Save Menu open state: {String(menuOpen)}

); } ``` ### Labelling the menu toggle The caret button has no visible text, so it is labelled `"Toggle menu"` for assistive technology by default. Pass `menuButtonAriaLabel` to override the default ARIA label: ```tsx demo import { SplitButton } from "@tenstorrent/vesper/split-button"; export default function LabelledSplitButton() { return ( {}} menuItems={[ { text: "Export as CSV", onSelect: () => {} }, { text: "Export as JSON", onSelect: () => {} }, ]} > Export ); } ``` ### Disabling a split button Pass `disabled` to disable both the action button and the caret button at the same time. The action button stops firing `onClick`, and the caret button no longer opens its menu: ```tsx demo import { SplitButton } from "@tenstorrent/vesper/split-button"; export default function DisabledSplitButton() { return ( {}} menuItems={[ { text: "Save as draft", onSelect: () => {} }, { text: "Save and publish", onSelect: () => {} }, ]} > Save ); } ``` > [!NOTE] > > There is no way to disable only one half of a `SplitButton`. When the alternatives are unavailable but the main action is not (or the other way around), render the individual items as `"disabled"` or `"locked"` [menu items](https://vesper.tenstorrent.com/components/menu.md) instead, so the reason stays visible to the user. --- Source: https://vesper.tenstorrent.com/components/status-indicator.md # Status Indicator A compact status label with a colored dot that communicates the current state of a process or resource. Supports five states and an optional pulsing animation. ```tsx demo import { StatusIndicator } from "@tenstorrent/vesper/status-indicator"; export default function StatusIndicatorDemo() { return ( ); } ``` ## Options | Prop | Type | Description | Default | | ---------- | ------------------------------------------------------------- | -------------------------------------------------------------------------- | ----------- | | `label` | `string` | The text label displayed next to the status dot. | — | | `state` | `"queued" \| "progress" \| "error" \| "ready" \| "cancelled"` | The current status state, which determines the color of the indicator dot. | — | | `variant` | `"default" \| "badge"` | The visual style variant of the status indicator. | `"default"` | | `animated` | `boolean` | When `true`, applies a pulsing animation to the status dot. | `false` | | `as` | `ElementType` | The root element type for polymorphic rendering. | `"div"` | Any additional props are forwarded to the wrapping `

` element, or whichever element is specified by the `as` prop. ## Examples ### Basic Usage Render a `StatusIndicator` by giving it a `state` and a `label`: ```tsx demo import { StatusIndicator } from "@tenstorrent/vesper/status-indicator"; export default function BasicStatusIndicator() { return ; } ``` ### Variants A `StatusIndicator` can be rendered in one of two visual variants: `"default"`, or `"badge"`. The default variant is `"default"`. When rendered using the `"badge"` variant, the `StatusIndicator` receives a subtle border, visually separating it from its surrounding content: ```tsx demo import { StatusIndicator } from "@tenstorrent/vesper/status-indicator"; export default function StatusIndicatorVariants() { return ( ); } ``` ### States `StatusIndicator` can be rendered with one of five states: `"queued"`, `"progress"`, `"error"`, `"ready"`, or `"cancelled"`. Use a `state` which corresponds with the status of the resource it describes. ```tsx demo import { StatusIndicator } from "@tenstorrent/vesper/status-indicator"; export default function StatusIndicatorStates() { return (

); } ``` ### Animating the indicator dot The colored dot next to the label can be rendered with a gentle pulsing animation by passing `animated={true}` or just `animated` as a prop: ```tsx demo import { StatusIndicator } from "@tenstorrent/vesper/status-indicator"; export default function AnimatedStatusIndicator() { return ; } ``` --- Source: https://vesper.tenstorrent.com/components/switch.md # Switch A toggle switch input with an optional label. Uses the native `switch` ARIA role for binary on/off states, with no indeterminate state. Supports controlled and uncontrolled modes. ```tsx demo import { Switch } from "@tenstorrent/vesper/switch"; export default function SwitchDemo() { return ; } ``` ## Options | Prop | Type | Description | Default | | ---------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------- | ------- | | `label` | `string` | The text label displayed next to the switch. An asterisk is appended when `required` is `true`. | — | | `size` | `"sm" \| "md"` | The size of the switch and its label. | `"md"` | | `ref` | `Ref` | A ref forwarded to the underlying `` element. | — | | `checked` | `boolean` | Controls the checked state (controlled mode). | — | | `defaultChecked` | `boolean` | The initial checked state (uncontrolled mode). | `false` | | `disabled` | `boolean` | When `true`, prevents interaction. | `false` | | `required` | `boolean` | When `true`, marks the input as required and appends an asterisk to the label. | `false` | | `onChange` | `ChangeEventHandler` | Callback fired when the switch is toggled. | — | Form and accessibility props such as `autoFocus`, `tabIndex`, `aria-label`, `aria-labelledby`, `aria-describedby`, `aria-invalid`, and event handlers like `onFocus`, `onBlur`, and `onKeyDown` are forwarded to the underlying `` element, as is `ref`. Any other props, including `className`, are forwarded to the wrapping `` element. Use the `Switch` component when toggling a setting on and off takes effect immediately. Reach for [the `Checkbox` component](https://vesper.tenstorrent.com/components/checkbox.md) instead when building form fields, such as accepting terms or opting into a mailing list, or when you need to represent an indeterminate state. ## Examples ### Controlled vs uncontrolled Render a `Switch` in an uncontrolled fashion to let it keep track of its own checked state. Pass `defaultChecked` if it should start out checked: ```tsx demo import { Switch } from "@tenstorrent/vesper/switch"; export default function UncontrolledSwitch() { return ; } ``` If you need to control whether the switch is checked, you can do so via the `checked` and `onChange` props. The new state is read from the event's `target.checked`: ```tsx demo import { useState } from "react"; import { Button } from "@tenstorrent/vesper/button"; import { Switch } from "@tenstorrent/vesper/switch"; import { Typography } from "@tenstorrent/vesper/typography"; export default function ControlledSwitch() { const [notificationsEnabled, setNotificationsEnabled] = useState(false); return (

setNotificationsEnabled(e.target.checked)} /> Checked: {String(notificationsEnabled)}

); } ``` ### Different sizes The `Switch` component can be rendered at `sm` or `md` size, defaulting to `md`. Size affects the dimensions of the switch itself, as well as the text styles of the text rendered beside it. ```tsx demo import { Switch } from "@tenstorrent/vesper/switch"; export default function SwitchSizes() { return (

); } ``` ### Disabling the switch You can disable a `Switch` by passing `disabled={true}` or just `disabled` as a prop. A disabled switch still displays its current state, but it cannot be toggled by pointer or keyboard, is skipped in the tab order, and is excluded from form data: ```tsx demo import { Switch } from "@tenstorrent/vesper/switch"; export default function DisabledSwitches() { return (

); } ``` ### Usage in forms `Switch` renders a native ``, so it works with regular form submission and native validation via props like `name`, `value`, `form`, and `required`. A switch that is turned on submits its value (defaulting to `"on"`), and a turned-off switch is omitted from form data entirely. Pass `required` when the switch must be turned on before the form can be submitted: ```tsx demo import { useState } from "react"; import { Button } from "@tenstorrent/vesper/button"; import { Switch } from "@tenstorrent/vesper/switch"; import { Typography } from "@tenstorrent/vesper/typography"; export default function FormSwitchDemo() { const [submitted, setSubmitted] = useState(null); return (

{ event.preventDefault(); const data = new FormData(event.currentTarget); setSubmitted(String(data.get("notifications") ?? "")); }} > {submitted !== null && ( Submitted value: notifications={submitted} )} ); } ``` The form above submits `notifications=enabled` once the switch is turned on, and refuses to submit at all while it is turned off. Use the `form` prop to associate the field with a ` ); } ``` ### Accessing the underlying element Use the `ref` prop when you need direct access to the underlying `` element, eg. to focus it or report a custom validation message: ```tsx import { useRef } from "react"; import { Switch } from "@tenstorrent/vesper/switch"; export default function SwitchRefDemo() { const ref = useRef(null); return ( ref.current?.setCustomValidity("")} onInvalid={() => ref.current?.setCustomValidity( "Telemetry must be enabled when opting into nightly builds", ) } /> ); } ``` --- Source: https://vesper.tenstorrent.com/components/tabs.md # Tabs A tabbed interface component for organizing content into switchable panels. Supports primary and secondary visual styles, icons in tab triggers, and controlled or uncontrolled selection. ```tsx demo import { Tabs } from "@tenstorrent/vesper/tabs"; import { Typography } from "@tenstorrent/vesper/typography"; export default function TabsDemo() { return ( Overview content., }, { label: "Settings", value: "settings", content: Settings content., }, { label: "Activity", value: "activity", content: Activity content., }, ]} /> ); } ``` ## Options | Prop | Type | Description | Default | | ---------------- | -------------------------- | --------------------------------------------------------------------------------- | ------------- | | `variant` | `"primary" \| "secondary"` | The visual style variant of the tabs. | `"primary"` | | `items` | `TabItem[]` | The list of tab items. Each has `label`, `value`, optional `icon`, and `content`. | — | | `value` | `string` | The value for the selected tab (controlled mode). | — | | `defaultValue` | `string` | The value of the tab to select by default (uncontrolled mode). | — | | `onValueChange` | `(value: string) => void` | Callback fired when a new tab is selected. | — | | `activationMode` | `"automatic" \| "manual"` | Whether a tab is activated on focus (`automatic`) or on click (`manual`). | `"automatic"` | All other props are forwarded to the underlying `

` element, which wraps the tab list and its panels. ### TabItem | Prop | Type | Description | Default | | --------- | ----------- | ---------------------------------------------------------- | ------- | | `label` | `string` | The text label displayed in the tab trigger. | — | | `value` | `string` | A unique value identifying this tab. | — | | `icon` | `ReactNode` | An optional icon element rendered before the label. | — | | `content` | `ReactNode` | The content rendered in the panel when this tab is active. | — | ## Examples ### Defining items Each entry in the `items` array describes a tab and the panel it reveals: `label` is the text in the trigger, `value` identifies the tab, and `content` is whatever should be rendered when it is active. Tabs are rendered in the order they are provided: ```tsx demo import { Tabs } from "@tenstorrent/vesper/tabs"; import { Typography } from "@tenstorrent/vesper/typography"; export default function BasicTabs() { return ( Everything you need to know about this item. ), }, { label: "History", value: "history", content: ( A log of every change made to this item. ), }, ]} /> ); } ``` ### Variants `Tabs` can be rendered in one of two variants. The default `primary` variant is meant for page-level navigation, while the more compact `secondary` variant suits switching between views inside a smaller container, such as a card or a panel: ```tsx demo import { Tabs } from "@tenstorrent/vesper/tabs"; import { Typography } from "@tenstorrent/vesper/typography"; export default function TabsVariants() { const items = [ { label: "Preview", value: "preview", content: The rendered output., }, { label: "Code", value: "code", content: The source code., }, ]; return (

); } ``` ### Rendering icons Pass an icon as a `ReactNode` to an item's `icon` prop to render it before that tab's label: ```tsx demo import { Gear, Globe } from "@tenstorrent/vesper/icons"; import { Tabs } from "@tenstorrent/vesper/tabs"; import { Typography } from "@tenstorrent/vesper/typography"; export default function TabsWithIcons() { return ( , content: General settings., }, { label: "Advanced", value: "advanced", icon: , content: Advanced settings., }, ]} /> ); } ``` ### Uncontrolled vs controlled Render `Tabs` in an uncontrolled fashion to let them keep track of their own selection, passing `defaultValue` to choose which tab is active initially. If you omit `defaultValue`, the first tab is selected initially. If you need to control which tab is selected, pass `value` alongside `onValueChange`: ```tsx demo import { useState } from "react"; import { Tabs } from "@tenstorrent/vesper/tabs"; import { Typography } from "@tenstorrent/vesper/typography"; export default function ControlledTabs() { const [tab, setTab] = useState("first"); return ( First panel., }, { label: "Second", value: "second", content: Second panel., }, ]} /> ); } ``` ### Activation mode By default, moving focus between tab triggers with the arrow keys activates each tab as it receives focus. Pass `activationMode="manual"` to require `Enter`, `Space`, or a click before the panel changes, which is the better choice when a panel's content is expensive to render or fetch: ```tsx demo import { Tabs } from "@tenstorrent/vesper/tabs"; import { Typography } from "@tenstorrent/vesper/typography"; export default function ManualTabs() { return ( Focus the tabs and use the arrow keys: the panel only changes once you press Enter or Space. ), }, { label: "Logs", value: "logs", content: Logs panel., }, ]} /> ); } ``` --- Source: https://vesper.tenstorrent.com/components/tag.md # Tag A small label component for categorizing or annotating content. Supports a wide range of color variants, three sizes, and an optional leading icon. ```tsx demo import { Tag } from "@tenstorrent/vesper/tag"; export default function TagDemo() { return Design; } ``` ## Options | Prop | Type | Description | Default | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ----------- | | `size` | `"sm" \| "md" \| "lg"` | The size of the tag. Affects height, padding, and icon size. | `"md"` | | `variant` | `"default" \| "contrast" \| "accent-bold" \| "accent-subtle" \| "danger-bold" \| "danger-subtle" \| "success-bold" \| "success-subtle" \| "info-bold" \| "info-subtle" \| "warning-bold" \| "warning-subtle"` | The color variant of the tag. | `"default"` | | `disabled` | `boolean` | When `true`, renders the tag in a disabled state and prevents interaction. | `false` | | `icon` | `ReactNode` | An optional icon element rendered to the left of the tag text. | — | | `as` | `ElementType` | The root element type for polymorphic rendering. | `"div"` | | `children` | `ReactNode` | The text content of the tag. | — | All other props are forwarded to the underlying `

` element, or whichever root element is specified via the `as` prop. Use a `Tag` to classify content into categories, such as topics on an article or labels on an issue. Reach for [the `Badge` component](https://vesper.tenstorrent.com/components/badge.md) when describing the content next to it (a plan tier, a role, a status), or [the `Chip` component](https://vesper.tenstorrent.com/components/chip.md) when the label represents a selection the user can toggle on and off. ## Examples ### Basic usage Render a `Tag` by giving it some children: ```tsx demo import { Tag } from "@tenstorrent/vesper/tag"; export default function BasicTag() { return Documentation; } ``` ### Variants `Tag` ships with two neutral variants and five colored variants. Each colored variant has both a bold and a subtle version (eg. `"accent-bold"`, `"accent-subtle"`). The default variant is `"default"`. Use bold color variants or the `"contrast"` variant when the tag should stand out from its surroundings. Use subtle color variants or the `"default"` variant when it should sit quietly alongside other content: ```tsx demo import { Tag } from "@tenstorrent/vesper/tag"; export default function TagVariants() { return (

Default Contrast Accent bold Accent subtle Success bold Success subtle Warning bold Warning subtle Danger bold Danger subtle Info bold Info subtle

); } ``` ### Different sizes A `Tag` can be rendered in one of three sizes; `"sm"`, `"md"`, or `"lg"`. The default size is `"md"`. Size affects the height and padding of the tag, as well as the dimensions of its icon: ```tsx demo import { Tag } from "@tenstorrent/vesper/tag"; export default function TagSizes() { return (

Small Medium Large

); } ``` ### Rendering an icon Pass an icon as a `ReactNode` to the `icon` prop to render it to the left of the tag's text: ```tsx demo import { Bolt, Bug } from "@tenstorrent/vesper/icons"; import { Tag } from "@tenstorrent/vesper/tag"; export default function TagsWithIcons() { return (

} variant="accent-bold"> Performance } variant="danger-subtle"> Bug

); } ``` ### Disabling a tag You can disable a `Tag` by passing `disabled={true}` or just `disabled` as a prop. A disabled tag renders with a muted color scheme that takes precedence over its `variant`, and prevents interaction when rendered as an interactive element: ```tsx demo import { Tag } from "@tenstorrent/vesper/tag"; export default function DisabledTag() { return (

Enabled Disabled

); } ``` ### Polymorphic usage You can use the `as` prop to specify what underlying element to render. In this case, we are passing `as="a"` to render the `Tag` as an anchor link, which is useful when a tag navigates to a filtered list of everything sharing that category: ```tsx demo import { Tag } from "@tenstorrent/vesper/tag"; export default function TagAsLink() { return ( Design ); } ``` --- Source: https://vesper.tenstorrent.com/components/text-area.md # Text Area A multi-line text input component that supports different visual variants. ```tsx demo import { TextArea } from "@tenstorrent/vesper/text-area"; export default function TextAreaDemo() { return (

);
}
```

> [!IMPORTANT]
>
> Always give a `TextArea` an accessible name by either [pairing it with a `<label>` via `htmlFor`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/htmlFor) or giving it an `aria-label`. Without one, assistive technology announces the field with no indication of what it is for.

## Options

| Prop          | Type                                             | Description                                                                                  | Default     |
| ------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------- | ----------- |
| `size`        | `"sm" \| "md" \| "lg"`                           | The size of the textarea. Affects padding and typography.                                    | `"md"`      |
| `variant`     | `"default" \| "warning" \| "success" \| "error"` | The visual variant, which determines color scheme.                                           | `"default"` |
| `height`      | `number`                                         | The fixed height of the textarea in pixels, scaling with base rem size.                      | `104`       |
| `ref`         | `Ref<HTMLTextAreaElement>`                       | A ref forwarded to the underlying `<textarea>` element.                                      | —           |
| `placeholder` | `string`                                         | Placeholder text for the textarea.                                                           | `" "`       |
| `maxLength`   | `number`                                         | The maximum number of characters the user can enter.                                         | —           |
| `minLength`   | `number`                                         | The minimum number of characters required for the field to be valid.                         | —           |
| `disabled`    | `boolean`                                        | When `true`, prevents interaction.                                                           | `false`     |
| `required`    | `boolean`                                        | When `true`, marks the textarea as required and appends an asterisk to the placeholder text. | `false`     |
| `readOnly`    | `boolean`                                        | When `true`, makes the textarea read-only.                                                   | `false`     |
| `resizeable`  | `boolean`                                        | When `true`, enables resizing the textarea.                                                  | `false`     |

Any other props are forwarded to the underlying `<textarea>` element.

Unlike [the `TextInput` component](https://vesper.tenstorrent.com/components/text-input.md), `TextArea` does not support icons or a `type` prop, since neither of them apply to multi-line text.

## Examples

### Uncontrolled vs controlled

Render a `TextArea` in an uncontrolled fashion to let it keep track of its own value:

```tsx demo
import { TextArea } from "@tenstorrent/vesper/text-area";

export default function UncontrolledTextArea() {
  return <TextArea aria-label="About" placeholder="Enter some text" />;
}
```

If you need to control the value of the `TextArea`, you can do so via the `value` and `onChange` props:

```tsx demo
import { useState } from "react";

import { TextArea } from "@tenstorrent/vesper/text-area";

export default function ControlledTextArea() {
  const [value, setValue] = useState("");

return (
    <TextArea
      aria-label="About"
      placeholder="Enter some text"
      value={value}
      onChange={(e) => setValue(e.target.value)}
    />
  );
}
```

### Different sizes

The `TextArea` component can be rendered at `sm`, `md`, or `lg` size, defaulting to `md`. Size affects the padding and text styles of the `textarea`.

```tsx demo
import { TextArea } from "@tenstorrent/vesper/text-area";

export default function TextAreaSizes() {
  return (
    <div
      style={{
        display: "flex",
        flexDirection: "column",
        gap: "var(--vesper-spacing-4)",
      }}
    >
      <TextArea size="sm" placeholder="A small TextArea" aria-label="About" />
      <TextArea size="md" placeholder="A medium TextArea" aria-label="About" />
      <TextArea size="lg" placeholder="A large TextArea" aria-label="About" />
    </div>
  );
}
```

### Setting the height

You can give a `TextArea` a fixed height in pixels via the `height` prop, which defaults to `104`. The value is converted to `rem`, so the rendered height scales with the base font size.

```tsx demo
import { TextArea } from "@tenstorrent/vesper/text-area";

export default function TextAreaHeight() {
  return (
    <TextArea
      aria-label="Release notes"
      placeholder="Summarize what changed in this release"
      height={200}
    />
  );
}
```

### Resizing the `TextArea`

By default, a `TextArea` does not resize. If you want to opt-into resizing behavior, you can pass `resizeable={true}` or just `resizeable`, which allows the `TextArea` to be resized along its block direction.

```tsx demo
import { TextArea } from "@tenstorrent/vesper/text-area";

export default function ResizeableTextArea() {
  return (
    <TextArea
      resizeable
      aria-label="Release notes"
      placeholder="Summarize what changed in this release"
    />
  );
}
```

### Disabling the textarea

You can disable the underlying textarea by passing `disabled={true}` or just `disabled` as a prop:

```tsx demo
import { TextArea } from "@tenstorrent/vesper/text-area";

export default function DisabledTextArea() {
  return (
    <TextArea
      aria-label="Overview"
      placeholder="Add a brief outline of your project"
      disabled
    />
  );
}
```

### Usage in forms

`TextArea` renders a native `<textarea>`, so it works with regular form submission and native validation via props like `name`, `form`, `required`, `minLength`, and `maxLength`:

```tsx
import { Button } from "@tenstorrent/vesper/button";
import { TextArea } from "@tenstorrent/vesper/text-area";

export default function FeedbackForm() {
  return (
    <form action="/api/feedback" method="post">
      <TextArea
        name="feedback"
        aria-label="Feedback"
        placeholder="What could we do better?"
        minLength={20}
        maxLength={500}
        required
      />
      <Button type="submit">Submit</Button>
    </form>
  );
}
```

### Accessing the underlying element

Use the `ref` prop when you need direct access to the underlying `<textarea>` element, eg. to focus it or read its selection:

```tsx
import { useRef } from "react";

import { TextArea } from "@tenstorrent/vesper/text-area";

export default function BioField() {
  const ref = useRef<HTMLTextAreaElement>(null);

return (
    <TextArea aria-label="Bio" placeholder="Tell us about yourself" ref={ref} />
  );
}
```

---

Source: https://vesper.tenstorrent.com/components/text-button.md

# Text Button

A minimal, text-only button without background or border. Supports multiple color variants, sizes, and optional leading or trailing icons. Ideal for inline actions and links.

```tsx demo
import { TextButton } from "@tenstorrent/vesper/text-button";

export default function TextButtonDemo() {
  return <TextButton>Learn more</TextButton>;
}
```

## Options

| Prop        | Type                                                                                                       | Description                                                        | Default    |
| ----------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ---------- |
| `size`      | `"sm" \| "md" \| "lg"`                                                                                     | The size of the text button. Affects font size.                    | `"md"`     |
| `variant`   | `"subtle" \| "contrast" \| "accent" \| "success" \| "warning" \| "danger" \| "info" \| "purple" \| "pink"` | The color variant of the text button.                              | `"accent"` |
| `disabled`  | `boolean`                                                                                                  | When `true`, renders in a disabled state and prevents interaction. | `false`    |
| `iconLeft`  | `ReactNode`                                                                                                | An optional icon element rendered to the left of the content.      | —          |
| `iconRight` | `ReactNode`                                                                                                | An optional icon element rendered to the right of the content.     | —          |
| `as`        | `ElementType`                                                                                              | The root element type for polymorphic rendering.                   | `"button"` |
| `children`  | `ReactNode`                                                                                                | The text content of the button.                                    | —          |

All other props are forwarded to the underlying `<button>` element, or whichever root element is specified via the `as` prop.

Use a `TextButton` for low-emphasis actions that sit inline with surrounding content. When an action needs a filled or outlined background, reach for [the `Button` component](https://vesper.tenstorrent.com/components/button.md); when it is represented by a single icon, reach for [the `IconButton` component](https://vesper.tenstorrent.com/components/icon-button.md).

## Examples

### Basic usage

Render a `TextButton` by giving it some children:

```tsx demo
import { TextButton } from "@tenstorrent/vesper/text-button";

export default function BasicTextButton() {
  return <TextButton onClick={() => console.log("clicked")}>Edit</TextButton>;
}
```

### Variants

A `TextButton` can be rendered in one of nine color variants. Pick the one that matches the meaning and/or urgency of the action. The default variant is `"accent"`:

```tsx demo
import { TextButton } from "@tenstorrent/vesper/text-button";

export default function TextButtonVariants() {
  return (
    <div
      style={{
        display: "flex",
        flexWrap: "wrap",
        gap: "var(--vesper-spacing-4)",
      }}
    >
      <TextButton variant="subtle">Subtle</TextButton>
      <TextButton variant="contrast">Contrast</TextButton>
      <TextButton variant="accent">Accent</TextButton>
      <TextButton variant="success">Success</TextButton>
      <TextButton variant="warning">Warning</TextButton>
      <TextButton variant="danger">Danger</TextButton>
      <TextButton variant="info">Info</TextButton>
      <TextButton variant="purple">Purple</TextButton>
      <TextButton variant="pink">Pink</TextButton>
    </div>
  );
}
```

### Different sizes

A `TextButton` can be rendered in one of three sizes; `"sm"`, `"md"`, or `"lg"`. The default size is `"md"`:

```tsx demo
import { TextButton } from "@tenstorrent/vesper/text-button";

export default function TextButtonSizes() {
  return (
    <div
      style={{
        display: "flex",
        alignItems: "center",
        gap: "var(--vesper-spacing-4)",
      }}
    >
      <TextButton size="sm">Small</TextButton>
      <TextButton size="md">Medium</TextButton>
      <TextButton size="lg">Large</TextButton>
    </div>
  );
}
```

### Rendering icons

A `TextButton` can render icons to the left or the right of its content via the `iconLeft` and `iconRight` props. Simply pass your icon as a `ReactNode` to either of these props:

```tsx demo
import { ArrowRight, Download } from "@tenstorrent/vesper/icons";
import { TextButton } from "@tenstorrent/vesper/text-button";

export default function TextButtonsWithIcons() {
  return (
    <div
      style={{
        display: "flex",
        gap: "var(--vesper-spacing-4)",
      }}
    >
      <TextButton iconLeft={<Download />}>Download</TextButton>
      <TextButton iconRight={<ArrowRight />}>Continue</TextButton>
    </div>
  );
}
```

### Disabling a text button

You can disable a `TextButton` by passing `disabled={true}` or just `disabled` as a prop. Disabling a button prevents interaction and changes the color scheme:

```tsx demo
import { TextButton } from "@tenstorrent/vesper/text-button";

export default function DisabledTextButton() {
  return <TextButton disabled>A disabled text button</TextButton>;
}
```

### Polymorphic usage

You can use the `as` prop to specify what underlying element to render. In this case, we are passing `as="a"` to render the `TextButton` as an anchor link, which is helpful when the action navigates somewhere instead of running a handler:

```tsx demo
import { ArrowRight } from "@tenstorrent/vesper/icons";
import { TextButton } from "@tenstorrent/vesper/text-button";

export default function TextButtonAsLink() {
  return (
    <TextButton as="a" href="#polymorphic-usage" iconRight={<ArrowRight />}>
      View documentation
    </TextButton>
  );
}
```

---

Source: https://vesper.tenstorrent.com/components/text-input.md

# Text Input

A text input component supporting different visual variants, as well as leading and trailing icons. Built on the native `<input>` element for full form compatibility.

```tsx demo
import { TextInput } from "@tenstorrent/vesper/text-input";

export default function TextInputDemo() {
  return (
    <TextInput aria-label="Email" placeholder="you@example.com" type="email" />
  );
}
```

> [!IMPORTANT]
>
> Always give a `TextInput` an accessible name by either [pairing it with a `<label>` via `htmlFor`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/htmlFor) or giving it an `aria-label`. Without one, assistive technology announces the field with no indication of what it is for.

## Options

| Prop              | Type                                                                                                                                     | Description                                                                                                       | Default     |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------- |
| `size`            | `"sm" \| "md" \| "lg"`                                                                                                                   | The size of the text input. Affects padding and typography.                                                       | `"md"`      |
| `variant`         | `"default" \| "warning" \| "success" \| "error"`                                                                                         | The visual variant, which determines color scheme.                                                                | `"default"` |
| `iconLeft`        | `ReactNode`                                                                                                                              | An optional icon rendered to the left of the input field.                                                         | —           |
| `iconLeftAction`  | `{ handler: (e: MouseEvent<HTMLButtonElement>) => void; ariaLabel: string }`                                                             | When provided, the left icon renders as a `<button>` that calls `handler` when clicked, labelled by `ariaLabel`.  | —           |
| `iconRight`       | `ReactNode`                                                                                                                              | An optional icon rendered to the right of the input field.                                                        | —           |
| `iconRightAction` | `{ handler: (e: MouseEvent<HTMLButtonElement>) => void; ariaLabel: string }`                                                             | When provided, the right icon renders as a `<button>` that calls `handler` when clicked, labelled by `ariaLabel`. | —           |
| `type`            | `"text" \| "email" \| "password" \| "url" \| "tel" \| "search" \| "number" \| "date" \| "datetime-local" \| "week" \| "month" \| "time"` | The HTML input type.                                                                                              | `"text"`    |
| `ref`             | `Ref<HTMLInputElement>`                                                                                                                  | A ref forwarded to the underlying `<input>` element.                                                              | —           |
| `placeholder`     | `string`                                                                                                                                 | Placeholder text for the input.                                                                                   | `" "`       |
| `disabled`        | `boolean`                                                                                                                                | When `true`, prevents interaction.                                                                                | `false`     |
| `required`        | `boolean`                                                                                                                                | When `true`, marks the input as required.                                                                         | `false`     |
| `readOnly`        | `boolean`                                                                                                                                | When `true`, makes the input read-only.                                                                           | `false`     |

Form props (`value`, `disabled`, `name`, `form`, etc.), input props (`autoCorrect`, `spellCheck`, `autoFocus`, etc.), `aria-*` attributes, `ref`, and event handlers related to `focus`, `blur`, `scroll`, `input`, and `change` events are forwarded to the underlying `<input>` element. All other props are forwarded to the wrapping `<div>` element.

## Examples

### Uncontrolled vs controlled

Render a `TextInput` in an uncontrolled fashion to let it keep track of its own value:

```tsx demo
import { TextInput } from "@tenstorrent/vesper/text-input";

export default function UncontrolledTextInput() {
  return <TextInput aria-label="About" placeholder="Enter some text" />;
}
```

If you need to control the value of the `TextInput`, you can do so via the `value` and `onChange` props:

```tsx demo
import { useState } from "react";

import { TextInput } from "@tenstorrent/vesper/text-input";

export default function ControlledTextInput() {
  const [value, setValue] = useState("");

return (
    <TextInput
      aria-label="About"
      placeholder="Enter some text"
      value={value}
      onChange={(e) => setValue(e.target.value)}
    />
  );
}
```

### Different sizes

The `TextInput` component can be rendered at `sm`, `md`, or `lg` size, defaulting to `md`. Size affects the padding and text styles of the input, as well as the size of the rendered icons.

```tsx demo
import { TextInput } from "@tenstorrent/vesper/text-input";

export default function TextInputSizes() {
  return (
    <div
      style={{
        display: "flex",
        flexDirection: "column",
        gap: "var(--vesper-spacing-4)",
      }}
    >
      <TextInput
        aria-label="Username"
        size="sm"
        placeholder="A small text input"
      />
      <TextInput
        aria-label="Username"
        size="md"
        placeholder="A medium text input"
      />
      <TextInput
        aria-label="Username"
        size="lg"
        placeholder="A large text input"
      />
    </div>
  );
}
```

### Rendering icons

You can render icons to the left or the right of the input via the `iconLeft` and `iconRight` props:

```tsx demo
import { Globe, Search } from "@tenstorrent/vesper/icons";
import { TextInput } from "@tenstorrent/vesper/text-input";

export default function TextInputWithIcons() {
  return (
    <TextInput
      aria-label="Search"
      placeholder="Enter some text"
      iconLeft={<Globe />}
      iconRight={<Search />}
    />
  );
}
```

Rendered icons can be treated as buttons by passing the `iconLeftAction` and `iconRightAction` props. Each action takes a `handler` that is called when the icon is clicked, and an `ariaLabel` that gives the resulting button an accessible label:

```tsx demo
import { Search } from "@tenstorrent/vesper/icons";
import { TextInput } from "@tenstorrent/vesper/text-input";

export default function TextInputWithIconAction() {
  return (
    <TextInput
      aria-label="Search term"
      placeholder="Enter some text"
      iconLeft={<Search />}
      iconLeftAction={{
        handler: () => console.log("Search logs"),
        ariaLabel: "Search logs",
      }}
    />
  );
}
```

### Disabling the input

You can disable a `TextInput` by passing `disabled={true}` or just `disabled` as a prop:

```tsx demo
import { TextInput } from "@tenstorrent/vesper/text-input";

export default function DisabledTextInput() {
  return (
    <TextInput
      aria-label="Byline"
      placeholder="Who wrote this article?"
      disabled
    />
  );
}
```

### Variants

The `TextInput` component can be rendered in one of four variants: `default`, `warning`, `success`, or `error`. The variant determines the colour scheme of the input.

#### Default variant

A `TextInput` renders with the `default` variant when no `variant` prop is specified:

```tsx demo
import { TextInput } from "@tenstorrent/vesper/text-input";

export default function DefaultTextInput() {
  return (
    <TextInput
      aria-label="Username"
      placeholder="Enter your desired username"
    />
  );
}
```

#### Warning variant

Use the `warning` variant to flag a value that needs attention, but that doesn't prevent the form from being submitted:

```tsx demo
import { TextInput } from "@tenstorrent/vesper/text-input";

export default function WarningTextInput() {
  return (
    <TextInput
      aria-label="Password"
      placeholder="Enter your password"
      variant="warning"
      type="password"
      defaultValue="password1"
    />
  );
}
```

#### Success variant

The `success` variant is best suited for confirming that a value has been validated as expected:

```tsx demo
import { useState } from "react";

import { TextInput } from "@tenstorrent/vesper/text-input";

export default function SuccessTextInput() {
  const [workspace, setWorkspace] = useState("vesper");

return (
    <TextInput
      aria-label="Workspace"
      placeholder="Enter the name of your workspace"
      variant="success"
      value={workspace}
      onChange={(e) => setWorkspace(e.target.value)}
    />
  );
}
```

#### Error variant

The `error` variant highlights an invalid value that must be corrected before the form can be submitted:

```tsx demo
import { useState } from "react";

import { TextInput } from "@tenstorrent/vesper/text-input";

export default function ErrorTextInput() {
  const [email, setEmail] = useState("you@example.com");

return (
    <TextInput
      aria-label="Email"
      placeholder="Enter your email"
      variant="error"
      type="email"
      value={email}
      onChange={(e) => setEmail(e.target.value)}
      required
    />
  );
}
```

### Usage in forms

`TextInput` renders a native `<input>`, so it works with regular form submission and native validation via props like `name`, `form`, `required`, `pattern`, `minLength`, and `maxLength`:

```tsx
import { Button } from "@tenstorrent/vesper/button";
import { TextInput } from "@tenstorrent/vesper/text-input";

export default function ContactForm() {
  return (
    <form action="/api/contact" method="post">
      <TextInput
        aria-label="Phone number"
        name="phone"
        type="tel"
        placeholder="555-555-5555"
        pattern="[0-9]{3}-[0-9]{3}-[0-9]{4}"
        required
      />
      <Button type="submit">Submit</Button>
    </form>
  );
}
```

### Accessing the underlying element

Use the `ref` prop when you need direct access to the underlying `<input>` element, eg. to focus it or read its selection:

```tsx
import { useRef } from "react";

import { Search } from "@tenstorrent/vesper/icons";
import { TextInput } from "@tenstorrent/vesper/text-input";

export default function SearchField() {
  const ref = useRef<HTMLInputElement>(null);

return (
    <TextInput
      aria-label="Search term"
      placeholder="Search logs"
      ref={ref}
      iconLeft={<Search />}
      iconLeftAction={{
        handler: () => ref.current?.focus(),
        ariaLabel: "Search logs",
      }}
    />
  );
}
```

---

Source: https://vesper.tenstorrent.com/components/theme-switcher.md

# Theme Switcher

A three-way toggle for switching between system, light, and dark color themes. Sets the `data-vesper-theme` attribute on the document element to control the active theme.

```tsx demo
import { ThemeSwitcher } from "@tenstorrent/vesper/theme-switcher";

export default function ThemeSwitcherDemo() {
  return (
    <div
      style={{
        display: "flex",
        alignItems: "center",
        gap: "var(--vesper-spacing-2)",
      }}
    >
      <ThemeSwitcher size="lg" />
      <ThemeSwitcher size="sm" />
    </div>
  );
}
```

## Options

| Prop   | Type           | Description                     | Default |
| ------ | -------------- | ------------------------------- | ------- |
| `size` | `"sm" \| "lg"` | The size of the theme switcher. | `"lg"`  |

## Examples

Render a `ThemeSwitcher` without any props. By default it renders at `lg` size:

```tsx demo
import { ThemeSwitcher } from "@tenstorrent/vesper/theme-switcher";

export default function BasicThemeSwitcher() {
  return <ThemeSwitcher />;
}
```

To specify a size, pass `size="sm"` or `size="lg"`:

```tsx demo
import { ThemeSwitcher } from "@tenstorrent/vesper/theme-switcher";

export default function ThemeSwitcherSizes() {
  return (
    <div
      style={{
        display: "flex",
        alignItems: "center",
        gap: "var(--vesper-spacing-2)",
      }}
    >
      <ThemeSwitcher size="sm" />
      <ThemeSwitcher size="lg" />
    </div>
  );
}
```

---

Source: https://vesper.tenstorrent.com/components/toast.md

# Toast

A notification system for displaying temporary messages at the bottom of the screen. Toasts support multiple variants, optional action buttons, auto-dismiss timeouts, and keyboard navigation. Render the `Toasts` container once in your app and use `addToast()` to trigger notifications.

```tsx demo
import { Button } from "@tenstorrent/vesper/button";
import { addToast } from "@tenstorrent/vesper/toast";

export default function ToastDemo() {
  return (
    <Button
      onClick={() => addToast({ content: "Hello from Vesper!", timeout: 5000 })}
    >
      Show toast
    </Button>
  );
}
```

## Options

### Toasts (Container)

| Prop        | Type                                                                                        | Description                                                                                 | Default           |
| ----------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ----------------- |
| `ariaLabel` | `string`                                                                                    | The accessible label for the toast region. The keyboard shortcut is automatically appended. | `"Notifications"` |
| `shortcut`  | `string \| { key: string; alt?: boolean; ctrl?: boolean; shift?: boolean; meta?: boolean }` | A keyboard shortcut that moves focus to the oldest active toast.                            | `"F8"`            |
| `container` | `Element \| DocumentFragment`                                                               | The DOM element to portal the toast container into.                                         | `document.body`   |

### `addToast` (Options)

| Prop          | Type                                                           | Description                                                                          | Default     |
| ------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ----------- |
| `content`     | `ReactNode`                                                    | The message content displayed inside the toast.                                      | —           |
| `variant`     | `"default" \| "success" \| "warning" \| "danger" \| "loading"` | The visual variant of the toast, which determines its icon and color.                | `"default"` |
| `timeout`     | `number \| false`                                              | Duration in milliseconds before the toast auto-dismisses. Set to `false` to disable. | `false`     |
| `action`      | `ToastAction`                                                  | An optional action to render a button at the bottom of the toast.                    | —           |
| `dismissText` | `string`                                                       | Customizes the `aria-label` text for the dismiss button.                             | `"Dismiss"` |

## Examples

### Basic usage

To enable usage of toasts in your application, you must first render the `Toasts` component once at the root level of your application. In a `Next.js` application, for example, you would render the `Toasts` component in your app's root `layout.tsx`.

```tsx
import { Toasts } from "@tenstorrent/vesper/toast";

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body>
        {children}
        <Toasts />
      </body>
    </html>
  );
}
```

Once you have rendered the `Toasts` component in your application, you can spawn toasts by calling the `addToast` function:

```tsx
addToast({ content: "Changes saved.", timeout: 5000 });
```

`addToast` can be called with the following set of options:

```tsx
interface ToastOptions {
  content: ReactNode;
  action?: {
    handler: () => void;
    content: ReactNode;
    altText?: string;
  };
  timeout?: number | false;
  variant?: ToastVariant;
  dismissText?: string;
}
```

### Toast variants

Toasts can be spawned with one of five variants: `"default"`, `"loading"`, `"success"`, `"warning"`, or `"danger"`.

For example, to spawn a warning variant toast that self-dismisses after 5 seconds, you would call `addToast` like so:

```tsx demo
import { Button } from "@tenstorrent/vesper/button";
import { addToast } from "@tenstorrent/vesper/toast";

export default function WarningToast() {
  return (
    <Button
      onClick={() =>
        addToast({
          content: "Resistance is futile.",
          variant: "warning",
          timeout: 5000,
        })
      }
    >
      Show toast
    </Button>
  );
}
```

### Self-dismissing toasts

Toasts by default do not dismiss themselves; you must specify a timeout duration if you want a toast to disappear on its own. If a user interacts with a toast by moving their cursor or keyboard focus into the toast, the timeout will stop, and restart once the user ceases to interact with the toast.

To spawn a self-dismissing toast, you must provide a `timeout`, which represents the duration in milliseconds the toast will be visible for:

```tsx demo
import { Button } from "@tenstorrent/vesper/button";
import { addToast } from "@tenstorrent/vesper/toast";

export default function SelfDismissingToast() {
  return (
    <Button
      onClick={() =>
        addToast({
          content: "This toast will dismiss itself!",
          timeout: 5000,
        })
      }
    >
      Show toast
    </Button>
  );
}
```

### Toasts with actions

You may spawn a toast with an associated call-to-action by passing an `action` object in the toast options:

```tsx demo
import { Button } from "@tenstorrent/vesper/button";
import { addToast } from "@tenstorrent/vesper/toast";

export default function ToastWithAction() {
  return (
    <Button
      onClick={() =>
        addToast({
          content: "Conversation archived.",
          timeout: 5000,
          variant: "success",
          action: {
            handler: () => console.log("You clicked the toast action button!"),
            content: "Undo",
            altText: "Go to archive to restore conversations.",
          },
        })
      }
    >
      Archive conversation
    </Button>
  );
}
```

Action objects have three properties:

1. `handler` – a callback function that fires when the call-to-action is clicked.
2. `content` – what appears inside the call-to-action (usually this will just be text, though any `ReactNode` is supported)
3. `altText` – short description of an alternative way for users to achieve the desired action. This field is important for screen reader users who may not be able to access the toast easily, especially if it is time-sensitive.

### Updating toasts

There may be situations where you want to update a toast while it's active. `addToast` will return a handle to the toast it spawned, which has the following type signature:

```tsx
interface ToastHandle {
  dismiss(): void;
  update(options: Partial<ToastOptions>): void;
}
```

Calling `dismiss()` will dismiss the toast, and calling `update()` will update the toast. For example, you could have a `"loading"` variant toast show while a network request is being made, then transition to either a `"success"` or `"warning"` variant and dismiss itself after a 5 second timeout when the request completes:

```tsx demo
import { Button } from "@tenstorrent/vesper/button";
import { addToast } from "@tenstorrent/vesper/toast";

export default function UpdatingToastDemo() {
  return (
    <Button
      onClick={async () => {
        // Spawn the toast
        const toast = addToast({
          content: "Fetching updates...",
          variant: "loading",
        });

// Await something asynchronous, like a timeout or network request
        await new Promise((resolve) => setTimeout(resolve, 3000));

// Update the toast
        toast.update({
          content: "Updates fetched!",
          variant: "success",
          timeout: 3000,
        });
      }}
    >
      Refresh feed
    </Button>
  );
}
```

---

Source: https://vesper.tenstorrent.com/components/toggle.md

# Toggle

A single-select toggle group that allows the user to choose one option from a set. Each option can display text or an icon.

```tsx demo
import { Toggle } from "@tenstorrent/vesper/toggle";

export default function ToggleDemo() {
  return (
    <Toggle
      defaultValue="monthly"
      options={[
        { value: "monthly", text: "Monthly" },
        { value: "yearly", text: "Yearly" },
      ]}
    />
  );
}
```

> [!IMPORTANT]
>
> Always give a `Toggle` an accessible name by either [pairing it with a `<label>` via `htmlFor`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/htmlFor) or giving it an `aria-label`. Without one, assistive technology announces the field with no indication of what it is for.

## Options

| Prop            | Type                      | Description                                                                                           | Default |
| --------------- | ------------------------- | ----------------------------------------------------------------------------------------------------- | ------- |
| `options`       | `ToggleOption[]`          | The list of toggle options. Each has `value` and either `text` or `icon` (with required `ariaLabel`). | —       |
| `size`          | `"sm" \| "md" \| "lg"`    | The size of the toggle and its options.                                                               | `"md"`  |
| `value`         | `string`                  | The currently selected value (controlled mode).                                                       | —       |
| `defaultValue`  | `string`                  | The initially selected value (uncontrolled mode).                                                     | —       |
| `onValueChange` | `(value: string) => void` | Callback fired when the selected value changes.                                                       | —       |
| `disabled`      | `boolean`                 | When `true`, disables all toggle options.                                                             | `false` |
| `name`          | `string`                  | The name of the underlying select, used as the field name when submitted with form data.              | —       |
| `required`      | `boolean`                 | When `true`, makes the underlying input required when rendered inside of a form.                      | `false` |

Any other props are forwarded to the wrapping `<div>` element.

### ToggleOption

| Prop        | Type        | Description                                                 | Default |
| ----------- | ----------- | ----------------------------------------------------------- | ------- |
| `value`     | `string`    | A unique value identifying this toggle option.              | —       |
| `text`      | `string`    | The text label displayed in the toggle option.              | —       |
| `icon`      | `ReactNode` | An icon element displayed instead of text.                  | —       |
| `ariaLabel` | `string`    | An accessible `aria-label`. Required for icon-only options. | —       |

## Examples

### Controlled vs uncontrolled

Render a `Toggle` in an uncontrolled fashion to let it keep track of its own state. Pass `defaultValue` if it should start out with a value pre-selected:

```tsx demo
import { Grid, List } from "@tenstorrent/vesper/icons";
import { Toggle } from "@tenstorrent/vesper/toggle";

export default function UncontrolledToggle() {
  return (
    <Toggle
      aria-label="Display options"
      defaultValue="grid"
      options={[
        { value: "grid", icon: <Grid />, ariaLabel: "Grid view" },
        { value: "list", icon: <List />, ariaLabel: "List view" },
      ]}
    />
  );
}
```

If you need to control the toggle's state, you can do so via the `value` and `onValueChange` props:

```tsx demo
import { useState } from "react";

import { Grid, List } from "@tenstorrent/vesper/icons";
import { Toggle } from "@tenstorrent/vesper/toggle";
import { Typography } from "@tenstorrent/vesper/typography";

export default function ControlledToggle() {
  const [value, setValue] = useState("");

return (
    <div
      style={{
        display: "flex",
        flexDirection: "column",
        gap: "var(--vesper-spacing-4)",
      }}
    >
      <Toggle
        aria-label="Display options"
        value={value}
        onValueChange={setValue}
        options={[
          { value: "list", icon: <List />, ariaLabel: "List view" },
          { value: "grid", icon: <Grid />, ariaLabel: "Grid view" },
        ]}
      />
      <Typography variant="copy-sm">
        Value: {value || "nothing selected"}
      </Typography>
    </div>
  );
}
```

### Text and icon options

You can render both text and icon options in a `Toggle`. To render text options, you would pass an array of `options` objects that each have `value` and `text` properties:

```tsx demo
import { Toggle } from "@tenstorrent/vesper/toggle";

export default function TextOptionsToggle() {
  return (
    <Toggle
      aria-label="Membership tier"
      options={[
        { value: "free", text: "Free" },
        { value: "basic", text: "Basic" },
        { value: "pro", text: "Pro" },
      ]}
      defaultValue="free"
    />
  );
}
```

To render icon options, pass an array of `options` objects that each have `value`, `icon`, and `ariaLabel` properties:

```tsx demo
import { Globe, Lock } from "@tenstorrent/vesper/icons";
import { Toggle } from "@tenstorrent/vesper/toggle";

export default function IconOptionsToggle() {
  return (
    <Toggle
      aria-label="Project visibility"
      options={[
        { value: "public", icon: <Globe />, ariaLabel: "Public" },
        { value: "private", icon: <Lock />, ariaLabel: "Private" },
      ]}
      defaultValue="public"
    />
  );
}
```

### Different sizes

`Toggle` can be rendered in one of three sizes; `"sm"`, `"md"`, or `"lg"`. The default size is `"md"`.

```tsx demo
import { Toggle } from "@tenstorrent/vesper/toggle";

export default function AllToggleSizes() {
  return (
    <div
      style={{
        display: "flex",
        flexDirection: "column",
        gap: "var(--vesper-spacing-4)",
      }}
    >
      <Toggle
        size="sm"
        defaultValue="monthly"
        aria-label="Billing period"
        options={[
          { value: "monthly", text: "Monthly" },
          { value: "yearly", text: "Yearly" },
        ]}
      />
      <Toggle
        size="md"
        defaultValue="monthly"
        aria-label="Billing period"
        options={[
          { value: "monthly", text: "Monthly" },
          { value: "yearly", text: "Yearly" },
        ]}
      />
      <Toggle
        size="lg"
        defaultValue="monthly"
        aria-label="Billing period"
        options={[
          { value: "monthly", text: "Monthly" },
          { value: "yearly", text: "Yearly" },
        ]}
      />
    </div>
  );
}
```

### Required fields

Passing `required` marks the toggle as required for native form validation:

```tsx
import { Toggle } from "@tenstorrent/vesper/toggle";

export default function RequiredToggleDemo() {
  return (
    <Toggle
      required
      name="billing_period"
      aria-label="Billing period"
      defaultValue="monthly"
      options={[
        { value: "weekly", text: "Weekly" },
        { value: "monthly", text: "Monthly" },
        { value: "yearly", text: "Yearly" },
      ]}
    />
  );
}
```

### Disabling the toggle

You can disable a `Toggle` by passing `disabled={true}` or just `disabled` as a prop. A disabled toggle still displays its current state, but it cannot be toggled by pointer or keyboard, is skipped in the tab order, and is excluded from form data:

```tsx demo
import { Toggle } from "@tenstorrent/vesper/toggle";

export default function DisabledToggle() {
  return (
    <Toggle
      disabled
      name="billing_period"
      aria-label="Billing period"
      defaultValue="monthly"
      options={[
        { value: "weekly", text: "Weekly" },
        { value: "monthly", text: "Monthly" },
        { value: "yearly", text: "Yearly" },
      ]}
    />
  );
}
```

### Usage in forms

`Toggle` renders a native `<select>`, so it works with regular form submission and native validation via props like `name`, `value`, `form`, and `required`.

Pass `required` when the toggle must have an option selected before the form can be submitted, such as a terms and conditions agreement:

```tsx demo
import { useState } from "react";

import { Button } from "@tenstorrent/vesper/button";
import { Toggle } from "@tenstorrent/vesper/toggle";
import { Typography } from "@tenstorrent/vesper/typography";

export default function FormToggleDemo() {
  const [submitted, setSubmitted] = useState<string>("");

return (
    <form
      style={{
        display: "flex",
        flexDirection: "column",
        gap: "var(--vesper-spacing-4)",
      }}
      onSubmit={(event) => {
        event.preventDefault();
        const data = new FormData(event.currentTarget);
        console.log(Object.fromEntries(data.entries()));
        setSubmitted(String(data.get("billing_period") ?? ""));
      }}
    >
      <Toggle
        name="billing_period"
        aria-label="Billing period"
        options={[
          { value: "weekly", text: "Weekly" },
          { value: "monthly", text: "Monthly" },
          { value: "yearly", text: "Yearly" },
        ]}
      />
      <Button size="sm" type="submit">
        Submit
      </Button>
      {!!submitted && (
        <Typography variant="copy-sm">Submitted value: {submitted}</Typography>
      )}
    </form>
  );
}
```

The form above submits `billing_period=monthly` when the "Monthly" toggle option is selected, and refuses to submit at all while the toggle is empty.

Use the `form` prop to associate the field with a `<form>` rendered elsewhere on the page:

```tsx
import { Button } from "@tenstorrent/vesper/button";
import { Toggle } from "@tenstorrent/vesper/toggle";

export default function ToggleFormPropDemo() {
  return (
    <div>
      <form id="signup" action="/api/signup" method="post">
        <Button type="submit">Create account</Button>
      </form>
      {/* rendered outside of the form, but submitted with it */}
      <Toggle
        required
        form="signup"
        name="billing_period"
        aria-label="Billing period"
        options={[
          { value: "weekly", text: "Weekly" },
          { value: "monthly", text: "Monthly" },
          { value: "yearly", text: "Yearly" },
        ]}
      />
    </div>
  );
}
```

### Accessing the underlying element

Use the `ref` prop when you need direct access to the underlying `<div>` element:

```tsx
import { useRef } from "react";
import { Toggle } from "@tenstorrent/vesper/toggle";

export default function ToggleRefDemo() {
  const ref = useRef<HTMLDivElement>(null);

return (
    <Toggle
      ref={ref}
      name="billing_period"
      aria-label="Billing period"
      options={[
        { value: "weekly", text: "Weekly" },
        { value: "monthly", text: "Monthly" },
        { value: "yearly", text: "Yearly" },
      ]}
    />
  );
}
```

---

Source: https://vesper.tenstorrent.com/components/tooltip.md

# Tooltip

A popup overlay that displays additional information when hovering over or focusing on a trigger element. Supports configurable positioning, delay duration, and max width.

```tsx demo
import { Button } from "@tenstorrent/vesper/button";
import { Tooltip } from "@tenstorrent/vesper/tooltip";

export default function TooltipDemo() {
  return (
    <Tooltip content="This is a tooltip">
      <Button variant="subtle">Hover me</Button>
    </Tooltip>
  );
}
```

## Options

| Prop            | Type                                                                                | Description                                                                               | Default    |
| --------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------- |
| `content`       | `ReactNode`                                                                         | The content displayed inside the tooltip popup.                                           | —          |
| `side`          | `"top" \| "right" \| "bottom" \| "left"`                                            | The preferred side to render the tooltip against.                                         | `"top"`    |
| `sideOffset`    | `number`                                                                            | The distance in pixels from the trigger to the tooltip (in addition to the arrow height). | `4`        |
| `align`         | `"center" \| "start" \| "end"`                                                      | The alignment of the tooltip relative to the trigger.                                     | `"center"` |
| `alignOffset`   | `number`                                                                            | An offset in pixels from the aligned edge.                                                | `0`        |
| `open`          | `boolean`                                                                           | Controls the open state of the tooltip (controlled mode).                                 | —          |
| `onOpenChange`  | `(value: boolean) => void`                                                          | Callback fired when the open state changes.                                               | —          |
| `delayDuration` | `number`                                                                            | Duration in milliseconds to wait before showing the tooltip.                              | `500`      |
| `defaultOpen`   | `boolean`                                                                           | Whether the tooltip is open by default (uncontrolled mode).                               | `false`    |
| `maxWidth`      | `number`                                                                            | The maximum width of the tooltip in pixels. Content wraps if exceeded.                    | `240`      |
| `container`     | `HTMLElement \| ShadowRoot \| null \| RefObject<HTMLElement \| ShadowRoot \| null>` | Specify the element or shadow root to portal the tooltip into.                            | –          |
| `children`      | `ReactNode`                                                                         | The trigger element that the tooltip is attached to.                                      | —          |

## Examples

### Basic usage

Render a `Tooltip` by wrapping children with it and giving it `content`. `content` can be any `ReactNode`, though it is highly advisable to just render plain text:

```tsx demo
import { IconButton } from "@tenstorrent/vesper/icon-button";
import { Download } from "@tenstorrent/vesper/icons";
import { Tooltip } from "@tenstorrent/vesper/tooltip";

export default function BasicTooltip() {
  return (
    <Tooltip content="Download documents">
      <IconButton
        aria-label="Download"
        variant="contrast"
        icon={<Download />}
      />
    </Tooltip>
  );
}
```

> [!IMPORTANT]
>
> A `Tooltip`'s children must be a single React element and able to receive event handlers to listen for hover events. A `Tooltip`'s content will not render otherwise.

### Positioning the tooltip

By default, a `Tooltip` floats above and is aligned to the center of its trigger. You can adjust the positioning of a `Tooltip` via the `side`, `sideOffset`, `align`, and `alignOffset` props.

The `side` prop determines which trigger edge the `Tooltip` sits against. Possible values are `"top"`, `"right"`, `"bottom"`, and `"left"`. The default value is `"top"`.

The `sideOffset` prop determines how far away in pixels the `Tooltip` is from its trigger's edge. The default value is `4`. This value scales with the base rem size.

The `align` prop determines which end of the `side` to align the `Tooltip` to. Possible values are `"start"`, `"end"`, and `"center"`. The default value is `"center"`.

The `alignOffset` prop adjusts how many pixels the `Tooltip` is offset from its alignment. The default value is `0`. This value scales with the base rem size.

The demo below shows how the `side` and `align` props interact with each other:

```tsx demo
import { useState } from "react";

import { Button } from "@tenstorrent/vesper/button";
import { Select } from "@tenstorrent/vesper/select";
import {
  Tooltip,
  TOOLTIP_ALIGNMENTS,
  TOOLTIP_SIDES,
  type TooltipAlign,
  type TooltipSide,
} from "@tenstorrent/vesper/tooltip";

export default function TooltipPositionPlayground() {
  const [side, setSide] = useState<TooltipSide>("top");
  const [align, setAlign] = useState<TooltipAlign>("center");

return (
    <div
      style={{ display: "flex", flexDirection: "column", alignItems: "center" }}
    >
      <Tooltip
        open
        side={side}
        align={align}
        content={`${side} side, ${align} align`}
      >
        <Button
          style={{
            marginTop: "var(--vesper-spacing-16)",
            marginBottom: "var(--vesper-spacing-20)",
          }}
        >
          Trigger
        </Button>
      </Tooltip>
      <div style={{ display: "flex", gap: "var(--vesper-spacing-4)" }}>
        <Select
          value={side}
          aria-label="Tooltip side"
          onValueChange={(side) => setSide(side as TooltipSide)}
          options={[...TOOLTIP_SIDES]}
          style={{ width: "var(--vesper-spacing-28)" }}
        />
        <Select
          value={align}
          aria-label="Tooltip align"
          onValueChange={(align) => setAlign(align as TooltipAlign)}
          options={[...TOOLTIP_ALIGNMENTS]}
          style={{ width: "var(--vesper-spacing-28)" }}
        />
      </div>
    </div>
  );
}
```

### Adjusting the delay

A `Tooltip` does not instantly show when a user hovers its trigger. By default, a half-second delay occurs prior to showing a `Tooltip`. This duration can be adjusted via the `delayDuration` prop, which represents the amount of milliseconds to wait before showing a `Tooltip`:

```tsx demo
import { Button } from "@tenstorrent/vesper/button";
import { Tooltip } from "@tenstorrent/vesper/tooltip";

export default function TooltipDelays() {
  return (
    <div
      style={{
        display: "flex",
        flexDirection: "column",
        alignItems: "flex-start",
        gap: "var(--vesper-spacing-4)",
      }}
    >
      <Tooltip
        content="This tooltip appears instantly"
        delayDuration={0}
        side="right"
      >
        <Button variant="contrast">No delay</Button>
      </Tooltip>
      <Tooltip
        content="This tooltip appears delayed"
        delayDuration={1000}
        side="right"
      >
        <Button variant="contrast">1 second delay</Button>
      </Tooltip>
    </div>
  );
}
```

### Setting the max width

The default maximum width a `Tooltip` can render at before its content wraps is `240` pixels. You can adjust this by passing a numeric value to the `maxWidth` prop. This value scales with the base rem size:

```tsx demo
import { Button } from "@tenstorrent/vesper/button";
import { Tooltip } from "@tenstorrent/vesper/tooltip";

export default function WideTooltip() {
  return (
    <Tooltip
      content="This tooltip contains a longer description that will wrap at the specified max width."
      maxWidth={320}
      side="right"
    >
      <Button variant="contrast">Details</Button>
    </Tooltip>
  );
}
```

### Controlling the open state

By default, a `Tooltip` tracks its own open state. If you need to control the open state of a `Tooltip`, you can do so via the `open` prop:

```tsx demo
import { Button } from "@tenstorrent/vesper/button";
import { Tooltip } from "@tenstorrent/vesper/tooltip";

export default function ControlledTooltips() {
  return (
    <div
      style={{
        display: "flex",
        flexDirection: "column",
        alignItems: "flex-start",
        gap: "var(--vesper-spacing-4)",
      }}
    >
      <Tooltip content="This tooltip is always showing" side="right" open>
        <Button variant="subtle">Hover me</Button>
      </Tooltip>
      <Tooltip content="This tooltip never shows" side="right" open={false}>
        <Button variant="subtle">Hover me</Button>
      </Tooltip>
    </div>
  );
}
```

Pair `open` with `onOpenChange` when you want to keep tracking hover and focus while still owning the state, eg. to keep a tooltip open while another part of the page is interacting with its trigger:

```tsx demo
import { useState } from "react";

import { Button } from "@tenstorrent/vesper/button";
import { Checkbox } from "@tenstorrent/vesper/checkbox";
import { Tooltip } from "@tenstorrent/vesper/tooltip";

export default function ControlledTooltip() {
  const [open, setOpen] = useState(false);
  const [pinned, setPinned] = useState(false);

return (
    <div
      style={{
        display: "flex",
        flexDirection: "column",
        alignItems: "flex-start",
        gap: "var(--vesper-spacing-4)",
      }}
    >
      <Tooltip
        content="The tooltip content"
        side="right"
        open={pinned || open}
        onOpenChange={setOpen}
      >
        <Button variant="subtle">Hover me</Button>
      </Tooltip>
      <Checkbox
        text="Keep the tooltip open"
        checked={pinned}
        onChange={(event) => setPinned(event.target.checked)}
      />
    </div>
  );
}
```

### Listening for `open`'s value changing

You can respond to `open`'s value changing via the `onOpenChange` prop:

```tsx demo
import { useState } from "react";

import { Button } from "@tenstorrent/vesper/button";
import { Tooltip } from "@tenstorrent/vesper/tooltip";
import { Typography } from "@tenstorrent/vesper/typography";

export default function TooltipOpenChange() {
  const [open, setOpen] = useState(false);

return (
    <div
      style={{
        display: "flex",
        flexDirection: "column",
        alignItems: "flex-start",
        gap: "var(--vesper-spacing-4)",
      }}
    >
      <Tooltip
        content="The tooltip content"
        side="right"
        onOpenChange={(open) => setOpen(open)}
      >
        <Button variant="subtle">Hover me</Button>
      </Tooltip>
      <Typography variant="copy-sm">Open state: {String(open)}</Typography>
    </div>
  );
}
```

### Showing by default

Pass `defaultOpen` to show a `Tooltip` before the first user interaction. Because this is uncontrolled mode, normal interactions can subsequently close it (pressing Escape or moving the pointer away after hovering, for example):

```tsx demo
import { Button } from "@tenstorrent/vesper/button";
import { Tooltip } from "@tenstorrent/vesper/tooltip";

export default function DefaultOpenTooltip() {
  return (
    <Tooltip content="This tooltip shows by default" side="right" defaultOpen>
      <Button variant="subtle">Hover me</Button>
    </Tooltip>
  );
}
```

---

Source: https://vesper.tenstorrent.com/components/typography.md

# Typography

A polymorphic text component that applies consistent typographic styles from the Vesper design system. Supports a wide range of display, heading, copy, and label variants.

```tsx demo
import { Typography } from "@tenstorrent/vesper/typography";

export default function TypographyDemo() {
  return (
    <Typography as="h2" variant="heading-lg">
      The quick brown fox
    </Typography>
  );
}
```

## Options

| Prop       | Type                | Description                                                                  | Default     |
| ---------- | ------------------- | ---------------------------------------------------------------------------- | ----------- |
| `variant`  | `TypographyVariant` | The typographic style variant to apply. See the full list of variants below. | `"copy-md"` |
| `as`       | `ElementType`       | The root element type for polymorphic rendering.                             | `"p"`       |
| `children` | `ReactNode`         | The text content.                                                            | —           |

All other props are forwarded to the underlying `<p>` element, or whichever root element is specified via the `as` prop.

### Available Variants

| Category | Variants                                                                                                                                                              |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Display  | `display-sm`, `display-md`, `display-lg`                                                                                                                              |
| Heading  | `heading-xs`, `heading-sm`, `heading-md`, `heading-lg`, `heading-xl`, `heading-2xl`                                                                                   |
| Copy     | `copy-xs`, `copy-xs-bold`, `copy-xs-mono`, `copy-sm`, `copy-sm-bold`, `copy-md`, `copy-md-bold`, `copy-lg`, `copy-lg-bold`, `copy-xl`, `copy-xl-bold`                 |
| Label    | `label-xs`, `label-xs-bold`, `label-xs-mono`, `label-sm`, `label-sm-bold`, `label-sm-mono`, `label-md`, `label-md-bold`, `label-md-mono`, `label-lg`, `label-lg-bold` |

A `variant` only controls how text looks; it has no bearing on the element that gets rendered. Pair it with the `as` prop so the rendered element matches the meaning of the text, eg. `as="h1"` for a page title, `as="a"` for inline links, etc.

## Examples

### Basic usage

Render `Typography` by giving it some children. Without a `variant` or `as` prop, it renders a `<p>` element styled with the `copy-md` variant:

```tsx demo
import { Typography } from "@tenstorrent/vesper/typography";

export default function BasicTypography() {
  return <Typography>Body copy for paragraphs and general content.</Typography>;
}
```

### Display variants

`display-*` variants are the largest text styles available, meant for hero sections and marketing pages:

```tsx demo
import { Typography } from "@tenstorrent/vesper/typography";

export default function DisplayTypography() {
  return (
    <div
      style={{
        display: "flex",
        flexDirection: "column",
        gap: "var(--vesper-spacing-2)",
      }}
    >
      <Typography variant="display-sm">Display small</Typography>
      <Typography variant="display-md">Display medium</Typography>
      <Typography variant="display-lg">Display large</Typography>
    </div>
  );
}
```

### Heading variants

`heading-*` variants cover the six levels of section titles you'll reach for within an interface:

```tsx demo
import { Typography } from "@tenstorrent/vesper/typography";

export default function HeadingTypography() {
  return (
    <div
      style={{
        display: "flex",
        flexDirection: "column",
        gap: "var(--vesper-spacing-2)",
      }}
    >
      <Typography as="h6" variant="heading-xs">
        Heading xs
      </Typography>
      <Typography as="h5" variant="heading-sm">
        Heading sm
      </Typography>
      <Typography as="h4" variant="heading-md">
        Heading md
      </Typography>
      <Typography as="h3" variant="heading-lg">
        Heading lg
      </Typography>
      <Typography as="h2" variant="heading-xl">
        Heading xl
      </Typography>
      <Typography as="h1" variant="heading-2xl">
        Heading 2xl
      </Typography>
    </div>
  );
}
```

### Copy variants

`copy-*` variants are for running text: paragraphs, descriptions, and anything else a user reads as prose:

```tsx demo
import { Typography } from "@tenstorrent/vesper/typography";

export default function CopyTypography() {
  return (
    <div
      style={{
        display: "flex",
        gap: "var(--vesper-spacing-4)",
      }}
    >
      <div
        style={{
          display: "flex",
          flexDirection: "column",
          gap: "var(--vesper-spacing-2)",
        }}
      >
        <Typography variant="copy-xs">Copy xs</Typography>
        <Typography variant="copy-xs-bold">Copy xs bold</Typography>
        <Typography variant="copy-sm">Copy sm</Typography>
        <Typography variant="copy-sm-bold">Copy sm bold</Typography>
        <Typography variant="copy-md">Copy md</Typography>
        <Typography variant="copy-md-bold">Copy md bold</Typography>
        <Typography variant="copy-lg">Copy lg</Typography>
        <Typography variant="copy-lg-bold">Copy lg bold</Typography>
        <Typography variant="copy-xl">Copy xl</Typography>
        <Typography variant="copy-xl-bold">Copy xl bold</Typography>
      </div>
    </div>
  );
}
```

### Label variants

`label-*` variants are for UI text rather than prose: form labels, buttons, table headers, and other short strings that annotate a control:

```tsx demo
import { Typography } from "@tenstorrent/vesper/typography";

export default function LabelTypography() {
  return (
    <div
      style={{
        display: "flex",
        flexDirection: "column",
        gap: "var(--vesper-spacing-2)",
      }}
    >
      <Typography as="span" variant="label-xs">
        Label xs
      </Typography>
      <Typography as="span" variant="label-sm">
        Label sm
      </Typography>
      <Typography as="span" variant="label-md">
        Label md
      </Typography>
      <Typography as="span" variant="label-lg">
        Label lg
      </Typography>
      <Typography as="span" variant="label-md-bold">
        Label md bold
      </Typography>
    </div>
  );
}
```

### Monospace variants

The `-mono` variants render in the design system's monospace font, which is useful for values where character alignment matters, such as identifiers, measurements, and timestamps:

```tsx demo
import { Typography } from "@tenstorrent/vesper/typography";

export default function MonoTypography() {
  return (
    <div
      style={{
        display: "flex",
        flexDirection: "column",
        gap: "var(--vesper-spacing-2)",
      }}
    >
      <Typography variant="copy-xs-mono">build-4f2c19a</Typography>
      <Typography as="span" variant="label-sm-mono">
        128.0 GB/s
      </Typography>
      <Typography as="span" variant="label-md-mono">
        2025-09-17T12:37:04Z
      </Typography>
    </div>
  );
}
```

> [!NOTE]
>
> To render a snippet of code inline with other text, reach for [the `Code` component](https://vesper.tenstorrent.com/components/code.md) instead, which renders monospaced text on a tinted background, sized to match the surrounding font size.

### Polymorphic usage

You can use the `as` prop to specify what underlying element to render:

```tsx demo
import { Typography } from "@tenstorrent/vesper/typography";

export default function PolymorphicTypography() {
  return (
    <div
      style={{
        display: "flex",
        flexDirection: "column",
        gap: "var(--vesper-spacing-2)",
      }}
    >
      <Typography as="h1" variant="display-sm">
        Welcome to Vesper
      </Typography>
      <Typography as="label" htmlFor="email" variant="label-md-bold">
        Email address
      </Typography>
      <Typography as="span" variant="copy-md-bold">
        Bold inline text
      </Typography>
    </div>
  );
}
```