Star Button
FreeA favourite toggle: an outline star that fills yellow when it is on, with a Tooltip that reads Star or Unstar.
npx wunderui-cli add star-buttonPlayground
Installation
npx wunderui-cli add star-buttonWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import { StarButton } from "@/components/wunderui/star-button"
import type { StarButtonProps } from "@/components/wunderui/star-button"Then use it:
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.
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 for
- Toggle for for a labelled two-state button in a toolbar
- Rating for for a score from 1 to 5 stars
- Icon Button for for an action that happens once, such as copy or share
Size
The star sits in an Icon Button, so it takes its sizes. Press one to switch it on: the star fills yellow and the Tooltip changes from Star to Unstar.
Keyboard interactions
The star is a native button, so the browser provides focus and activation.
- Tab
- Moves focus to the button and opens its Tooltip.
- EnterorSpace
- Switches the star on or off.
Behavior and motion
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
The figure shows the button switched on, enlarged.
The quiet Icon Button that holds the star. It is a native button with aria-pressed, so it is one tab stop.
- data-slot="star-button"
The outline star. Switched on it fills with the yellow of the warning tokens and the button takes the same yellow for its icon.
Our Tooltip, opened on hover and focus. It reads Star while the button is off and Unstar while it is on.
Best practices
- Do
Give it a label that names the thing, such as Star Q3 report.pdf, when several stars share a screen.
- Do
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
Don't use it as an on or off setting. Switch and Toggle say that in words.
API reference
One table. StarButton is an Icon Button, so it also takes the Icon Button props (size, variant, shape).
The quiet Icon Button that holds the star. It is a native button with aria-pressed, so it is one tab stop.
| Prop | Type | Default | Description |
|---|---|---|---|
| starred | boolean | — | Controlled state. Leave it out and the button keeps its own. It sets aria-pressed. |
| defaultStarred | boolean | false | The starting state when the button keeps its own. Defaults to false. |
| onStarredChange | (starred: boolean) => void | — | Called with the new state when the button is pressed. |
| label | string | "Star" | The accessible name, such as Star Q3 report.pdf. The pressed state says whether it is on. Defaults to Star. |
| tooltipSide | "top" | "bottom" | "left" | "right" | "top" | Where the Tooltip opens. Defaults to top. |
| 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. |
| nativeButton | boolean | true | Whether the component renders a native element when replacing it via the prop. Set to if the rendered element is not a button (for example, ). |
| 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… |
| shape | "circle" | "rounded" | — | |
| size | "lg" | "xl" | "sm" | "md" | "2xl" | "sm" | |
| variant | "plain" | "gradient" | "outline" | "primary" | "destructive" | "light" | "ghost" | "brand" | "dark" | "ghost" |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("star-button")npx wunderui-cli add star-buttonThe full library index for assistants is at /llms.txt.