Spectrum UI

https://ui.spectrumhq.in/docs
Admin
Spectrum UI is an open-source React component and block library built with Next.js, Tailwind CSS,...
Tokens:59,874
Snippets:833
Trust Score:3.2
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install a component with bunx or npx

Source: https://ui.spectrumhq.in/docs/mcp

Commands that run behind the scenes when the MCP server installs a component. The first tries Bun, the second falls back to npm/pnpm/yarn. You can also run them manually; they appear on every component's docs page in the Installation section.

```bash
bunx --bun shadcn@latest add @spectrumui/<component-name>
```

```bash
npx shadcn@latest add @spectrumui/<component-name>
```

--------------------------------

### ReactionBar

Source: https://ui.spectrumhq.in/docs/reaction-bar

Documentation for the ReactionBar component, including its props and usage example.

```APIDOC
## ReactionBar

### Description
Renders a row of reaction chips, each a `button` with `aria-pressed` reflecting whether you have reacted. Reactions use the exported `Reaction` type: `{ emoji: string; count: number; reacted?: boolean }`. Pass `reactions` to control the list from outside, or `defaultReactions` to let it manage its own state. Toggling a chip adjusts its count by one, and a chip whose count reaches zero is removed.

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `reactions` | `Reaction[]` | - | Controlled reactions. Leave undefined for uncontrolled usage |
| `defaultReactions` | `Reaction[]` | `[]` | Initial reactions when uncontrolled |
| `onReactionsChange` | `(reactions: Reaction[]) => void` | - | Fires with the next reactions array on every change |
| `availableEmojis` | `string[]` | `["👍", "❤️", "😂", "🎉", "😮", "🚀"]` | Emojis offered in the add popover |
| `addable` | `boolean` | `true` | Show the plus button that opens the emoji popover |
| `size` | `"sm" | "md"` | `"md"` | Visual size of the chips |
| `className` | `string` | - | Additional classes merged with the default container styles |

### Usage Example

```jsx
import { ReactionBar } from "@/components/spectrumui/reaction-bar"

<ReactionBar
  defaultReactions={[
    { emoji: "👍", count: 3, reacted: true },
    { emoji: "🎉", count: 1 },
  ]}
  onReactionsChange={(reactions) => console.log(reactions)}
/>
```
```

--------------------------------

### Initialize shadcn/ui with pnpm dlx shadcn@latest init

Source: https://ui.spectrumhq.in/docs/installation

Initializes shadcn/ui in your project. Installs required packages and prepares Tailwind CSS. Add the -d flag to skip questions and use default settings.

```shell
pnpm dlx shadcn@latest init
```

--------------------------------

### Usage example

Source: https://ui.spectrumhq.in/docs/expandable-action-bar

Renders an ExpandableActionBar with two items (Edit and Share) and an onAction handler that calls run(item.id).

```tsx
<ExpandableActionBar
  items={[
    { id: "edit", label: "Edit", icon: <Pencil className="size-4" />, shortcut: "E" },
    { id: "share", label: "Share", icon: <Share2 className="size-4" /> },
  ]}
  onAction={(item) => run(item.id)}
/>
```

--------------------------------

### StarRating

Source: https://ui.spectrumhq.in/docs/star-rating

Documentation for the StarRating component, including its props and usage example.

```APIDOC
## StarRating

### Description
Renders a `radiogroup` of star buttons with full arrow-key, Home/End and Space/Enter keyboard support. Pass `value` to control it from outside, or `defaultValue` to let it manage its own state. In `readOnly` mode it renders a static, fraction-capable display.

### Props
- **value** (`number`) - Optional - Controlled rating value. Leave undefined for uncontrolled usage
- **defaultValue** (`number`, default: `0`) - Optional - Initial rating when uncontrolled
- **onValueChange** (`(value: number) => void`) - Optional - Fires with the next rating on every commit
- **max** (`number`, default: `5`) - Optional - Number of stars rendered
- **size** (`"sm" | "md" | "lg"`, default: `"md"`) - Optional - Visual size of the stars (16 / 22 / 28 px icons)
- **allowClear** (`boolean`, default: `true`) - Optional - Clicking the committed star again clears the rating to 0
- **readOnly** (`boolean`, default: `false`) - Optional - Display-only mode without hover or click interactivity; supports fractional values like 4.3
- **showValue** (`boolean`, default: `false`) - Optional - Show a rolling "4/5" value label that tracks the current or previewed rating
- **label** (`string`, default: `"Rating"`) - Optional - Accessible name of the rating group
- **className** (`string`) - Optional - Additional classes merged with the default container styles

### Usage Example
```jsx
import { StarRating } from "@/components/spectrumui/star-rating"

<StarRating showValue onValueChange={(value) => console.log(value)} />
```
```

--------------------------------

### Example usage of BeamSearch

Source: https://ui.spectrumhq.in/docs/beam-search

Example JSX usage of the BeamSearch component with a placeholder, onChange, and onSubmit handlers. This demonstrates how to integrate the component and manage its state.

```jsx
<BeamSearch
  placeholder="Search components…"
  onChange={setQuery}
  onSubmit={runSearch}
/>

```

--------------------------------

### Import and render CommandSearch with queries and onSelect

Source: https://ui.spectrumhq.in/docs/command-search

Import the CommandSearch component from the local spectrumui path, then render it with a list of queries and an onSelect handler that logs the selected item's label. The component types each query and live-filters grouped results by default.

```tsx
import { CommandSearch } from "@/components/spectrumui/command-search"
```

```tsx
<CommandSearch
  queries={["chart", "button", "pricing"]}
  onSelect={(item) => console.log(item.label)}
/>
```

--------------------------------

### BeamCard usage example

Source: https://ui.spectrumhq.in/docs/beam-card

Example usage of the BeamCard component with the pulse-outside size, ocean color variant, and custom content. The beam hugs the card's border radius.

```tsx
<BeamCard
  size="pulse-outside"
  colorVariant="ocean"
  eyebrow="Pro"
  title="Edge inference"
  description="Models run in the region closest to the user."
/>
```

--------------------------------

### AvatarStack

Source: https://ui.spectrumhq.in/docs/avatar-stack

Documentation for the AvatarStack component, including its props and usage example.

```APIDOC
## AvatarStack

### Description
Renders a `role="group"` of avatar buttons with roving arrow-key focus; each item is an `AvatarItem` of shape `{ name: string; src?: string }`. When `src` is omitted, initials are derived from the first two words of `name`. The name also becomes the button's `aria-label` and the tooltip text, and `Escape` collapses an expanded stack.

### Props
- **items** (`AvatarItem[]`) - Required - People to render; the first max are visible, the rest sit behind the +N pill
- **max** (`number`) - Optional, default `4` - Number of avatars shown before overflowing into the +N pill
- **size** (`"sm" | "md" | "lg"`) - Optional, default `"md"` - Avatar diameter: 28, 36 or 44px
- **expandable** (`boolean`) - Optional, default `true` - Whether clicking the +N pill expands the hidden avatars with a stagger
- **onAvatarClick** (`(item: AvatarItem, index: number) => void`) - Optional - Fires when an avatar is clicked or activated with Enter/Space
- **className** (`string`) - Optional - Additional classes merged onto the group container

### Usage Example
```jsx
<AvatarStack
  items={[
    { name: "Arjun Mehta", src: "/avatars/people/01.jpg" },
    { name: "Priya Nair", src: "/avatars/people/05.jpg" },
    { name: "Noah Kim", src: "/avatars/people/06.jpg" },
  ]}
  onAvatarClick={(item) => console.log(item.name)}
/>
```
```

--------------------------------

### Import KbdKey and KbdCombo

Source: https://ui.spectrumhq.in/docs/kbd-key

Import the KbdKey and KbdCombo components from the local spectrumui components directory.

```tsx
import { KbdKey, KbdCombo } from "@/components/spectrumui/kbd-key"
```

--------------------------------

### TransferFundsCard

Source: https://ui.spectrumhq.in/docs/transfer-funds-card

Documentation for the TransferFundsCard React component, including its props and usage example.

```APIDOC
## TransferFundsCard

### Description
A presentational form card for transferring funds between accounts. It includes an amount field, source and destination account pickers, a summary table, and a confirm button. All labels and values are configurable via props.

### Props
- **amount** (`string`) - Default: `"1,200.00"` - Formatted amount shown in the amount field
- **currencySymbol** (`string`) - Default: `"$"` - Symbol shown before the amount
- **fromAccount** (`string`) - Required - Text of the source account picker
- **toAccount** (`string`) - Required - Text of the destination account picker
- **summary** (`{ label: string; value: string; emphasized?: boolean }[]`) - Required - Rows of the summary table; emphasized rows render bold
- **title** (`string`) - Default: `"Transfer Funds"` - Card heading
- **description** (`string`) - Default: `"Move money between your connected accounts."` - Supporting copy under the heading
- **amountLabel** (`string`) - Default: `"Amount to Transfer"` - Label for the amount field
- **fromLabel** (`string`) - Default: `"From Account"` - Label for the source picker
- **toLabel** (`string`) - Default: `"To Account"` - Label for the destination picker
- **buttonLabel** (`string`) - Default: `"Confirm Transfer"` - Confirm button text
- **onConfirm** (`() => void`) - Required - Fires when the confirm button is pressed
- **onClose** (`() => void`) - Optional - Fires when the close button in the header is pressed
- **className** (`string`) - Optional - Additional classes merged with the root styles

### Usage Example
```jsx
import { TransferFundsCard } from "@/components/spectrumui/transfer-funds-card"

<TransferFundsCard
  amount="1,200.00"
  fromAccount="Main Checking (··8402) — ,450.00"
  toAccount="High Yield Savings (··1192) — ,100.00"
  onConfirm={() => console.log("confirm")}
/>
```
```

--------------------------------

### Import QuantityStepper

Source: https://ui.spectrumhq.in/docs/quantity-stepper

Import the QuantityStepper component from the local components directory.

```javascript
import { QuantityStepper } from "@/components/spectrumui/quantity-stepper"
```

--------------------------------

### Render KbdKey and KbdCombo

Source: https://ui.spectrumhq.in/docs/kbd-key

Render a single keycap with the label K, and a combo that listens for meta+k and fires the onTrigger callback when all keys are held simultaneously.

```tsx
<KbdKey>K</KbdKey>
<KbdCombo keys="meta+k" onTrigger={() => console.log("open palette")} />
```

--------------------------------

### Create a new Next.js project

Source: https://ui.spectrumhq.in/docs/installation

Creates a new Next.js project. Run this in your terminal to scaffold a new project, or skip if you already have one.

```shell
pnpm create next-app@latest
```

--------------------------------

### SwipeToDelete usage example

Source: https://ui.spectrumhq.in/docs/swipe-to-delete

Wrap a row component with SwipeToDelete, providing a label and an onDelete callback that removes the item from state.

```tsx
<SwipeToDelete label="email from Ava" onDelete={() => removeEmail(id)}>
  <EmailRow />
</SwipeToDelete>
```

--------------------------------

### Render AnimatedSwitch with defaultChecked and onCheckedChange

Source: https://ui.spectrumhq.in/docs/animated-switch

Renders the AnimatedSwitch component with defaultChecked and an onCheckedChange handler that logs the checked state. This is the basic usage example.

```tsx
<AnimatedSwitch defaultChecked onCheckedChange={(checked) => console.log(checked)} />
```

--------------------------------

### Import ReactionBar component

Source: https://ui.spectrumhq.in/docs/reaction-bar

Import the ReactionBar component from the directory '@/components/spectrumui/reaction-bar'.

```JavaScript
import { ReactionBar } from "@/components/spectrumui/reaction-bar"
```

--------------------------------

### Render NumberTicker with value, prefix, locale, and blur

Source: https://ui.spectrumhq.in/docs/number-ticker

Render the NumberTicker with a value of 48250, a dollar sign prefix, locale group separators, and blur during rolls. This example is shown in the Usage section.

```tsx
<NumberTicker value={48250} prefix="$" locale blur />
```

--------------------------------

### Use TextStates in a button

Source: https://ui.spectrumhq.in/docs/text-states

Example usage of the TextStates component inside a button. The text prop changes based on the saving and saved state variables, triggering the exit and enter swap animation.

```tsx
<button onClick={save}>
  <TextStates text={saving ? "Saving…" : saved ? "Saved" : "Save"} />
</button>
```
Tokens:
Raw