Skip to content
WunderUI

Star Button

Free

A 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-button

Playground

Installation

bash
npx wunderui-cli add star-button

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

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

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.

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.

PropTypeDefaultDescription
starredboolean—Controlled state. Leave it out and the button keeps its own. It sets aria-pressed.
defaultStarredbooleanfalseThe 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.
labelstring"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.
expandedboolean—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.
focusableWhenDisabledbooleanfalseWhether the button should be focusable when disabled.
nativeButtonbooleantrueWhether the component renders a native element when replacing it via the prop. Set to if the rendered element is not a button (for example, ).
pendingboolean—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.

MCPget_component("star-button")
Installnpx wunderui-cli add star-button

The full library index for assistants is at /llms.txt.