# Star Button

A favourite toggle: an outline star that fills yellow, with a Tooltip that reads Star or Unstar.

- Category: Core Elements
- Page: https://wunderui.com/components/star-button
- Tier: Free

## Install

```bash
npx wunderui-cli add star-button
```

## Import

```tsx
import { StarButton, StarButtonProps } from "@/components/wunderui/star-button"
```

## Minimal usage

Then use it:

```tsx
import { StarButton } from "@wunderui/react"

export function Favourite() {
  return <StarButton />
}
```

Expected result: You see an outline star in a quiet square button. Press it and the star fills yellow, and the Tooltip reads Unstar.

## Usage

```tsx
import { StarButton } from "@wunderui/react"

export function Favourite() {
  return <StarButton defaultStarred />
}
```

## When to use

### Use Star Button for

- Marking a file, project or message as a favourite
- A quiet control in a header or a row, next to a title
- A choice that is saved per user and can be undone with one press

### Use something else

- [Toggle](https://wunderui.com/components/toggle) for for a labelled two-state button in a toolbar
- [Rating](https://wunderui.com/components/rating) for for a score from 1 to 5 stars
- [Icon Button](https://wunderui.com/components/icon-button) for for an action that happens once, such as copy or share

## Keyboard

The star is a native button, so the browser provides focus and activation.

| Key | Action |
|---|---|
| `Tab` | Moves focus to the button and opens its Tooltip. |
| `Enter` or `Space` | Switches the star on or off. |

## Behavior

What the button does with state, names and motion.

- **State:** Without starred the button keeps its own state, starting from defaultStarred. With starred it follows your value and only reports a press through onStarredChange.
- **Name:** The accessible name is the label (default Star) and aria-pressed carries the state, so a screen reader says Star, toggle button, pressed. The name does not change with the state.
- **Tooltip:** The Tooltip is our Tooltip and says Star or Unstar. It closes when the button is pressed.
- **Colour:** Switched on, the star is filled with --yellow-600 and drawn in --yellow-700. The colour is never the only sign: the fill and aria-pressed change too.

## Anatomy

- `StarButton`: The quiet Icon Button that holds the star. It is a native button with aria-pressed, so it is one tab stop.
- `Star`: The outline star. Switched on it fills with the yellow of the warning tokens and the button takes the same yellow for its icon.
- `Tooltip`: Our Tooltip, opened on hover and focus. It reads Star while the button is off and Unstar while it is on.
- `Star Button`

## Best practices

### When to use

- Use it to mark one thing as a favourite: a file, a project, a message or a saved view.

### Do

- Give it a label that names the thing, such as Star Q3 report.pdf, when several stars share a screen.
- Keep the state in your data and pass starred with onStarredChange when it has to be saved.

### Don't

- Don't use it for a rating of 1 to 5 stars. Rating is the component for that.
- Don't use it as an on or off setting. Switch and Toggle say that in words.

## API reference

### StarButton

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| defaultStarred | boolean | false | The starting state when the button keeps its own. Defaults to false. |
| expanded | boolean |  | Marks a trigger whose menu or panel is open: sets aria-expanded and the pressed surface (bg-bg-subtle) on the quiet variants. Leave it undefined when the button does not control a popup. |
| focusableWhenDisabled | boolean | false | Whether the button should be focusable when disabled. |
| label | string | "Star" | The accessible name, such as Star Q3 report.pdf. The pressed state says whether it is on. Defaults to Star. |
| nativeButton | boolean | true | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |
| onStarredChange | (starred: boolean) => void |  | Called with the new state when the button is pressed. |
| pending | boolean |  | Shows a spinner in place of the icon, in the same square, and ignores presses. The button stays focusable and keeps its colour (it is not disabled). |
| phase | "error" \| "success" \| "pending" \| "idle" |  | Async feedback in the same square: pending shows a spinner, success a check, error a retry icon. The size never changes. The accessible name is yours: change the aria-label with the phase (for example Copy link, Copying, Copied, Retry copy… |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| shape | "circle" \| "rounded" |  |  |
| size | "lg" \| "xl" \| "sm" \| "md" \| "2xl" | "sm" |  |
| starred | boolean |  | Controlled state. Leave it out and the button keeps its own. It sets aria-pressed. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |
| tooltipSide | "top" \| "bottom" \| "left" \| "right" | "top" | Where the Tooltip opens. Defaults to top. |
| variant | "plain" \| "gradient" \| "outline" \| "primary" \| "destructive" \| "light" \| "ghost" \| "brand" \| "dark" | "ghost" |  |

Also accepts React.ButtonHTMLAttributes attributes.

## Examples

### Size: the three Icon Button sizes, off and on

```tsx
import { StarButton } from "@wunderui/react"

export function Favourite() {
  return <StarButton size="sm" />
}
```

## In context

### Controlled: the parent keeps the state

Pass `starred` and `onStarredChange` when the state is saved somewhere, and give the button a `label` that names what is starred.

```tsx
import { useState } from "react"
import { StarButton } from "@wunderui/react"

export function PinFile() {
  const [starred, setStarred] = useState(false)
  return <StarButton starred={starred} onStarredChange={setStarred} label="Star Q3 report.pdf" />
}
```

### File header: next to the title

A quiet button beside a heading. The Tooltip opens below so it does not cover the title.

```tsx
import { useState } from "react"
import { StarButton } from "@wunderui/react"

export function FileHeader() {
  const [starred, setStarred] = useState(true)
  return (
    <header className="flex items-center gap-2">
      <h2 className="text-lg font-semibold">Q3 report.pdf</h2>
      <StarButton starred={starred} onStarredChange={setStarred} label="Star Q3 report.pdf" tooltipSide="bottom" />
    </header>
  )
}
```

## For AI agents

`get_component("star-button")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
