Favorite button React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Favorite button is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import FavoriteButton from @/components/ui/favorite-button.

import { FavoriteButton } from "@/components/ui/favorite-button"

const labels = {
  name: "Save listing",
  add: "Add to your watchlist",
  remove: "Remove from your watchlist",
  error: "We could not save it. Try again.",
}

export function ListingPhoto({ saved, onSave }: { saved: boolean; onSave: (saved: boolean) => Promise<unknown> }) {
  return (
    <div className="relative aspect-[4/3] overflow-hidden rounded-2xl bg-foreground/5">
      <img src="/demo/bicycle.jpg" alt="Pegas Popular city bike" className="size-full object-cover" />
      <FavoriteButton
        variant="overlay"
        tone="danger"
        pressed={saved}
        onPressedChange={onSave}
        labels={labels}
        className="absolute end-2.5 top-2.5"
      />
    </div>
  )
}

Props

• defaultPresseddefault false
  boolean

  Starts saved. The button then owns its state.

• pressed
  boolean

  Controlled on / off. While a request is pending, a change of this prop wins and the pending answer is ignored.

• onPressedChange
  ((pressed: boolean) => void | Promise<unknown>)

  Called with the new state when a person toggles it. Return a promise to keep the optimistic state while it is pending (clicks are ignored meanwhile); a rejection, or a synchronous throw, rolls back, shakes, buzzes on touch and announces labels.error.

• variantdefault "ghost"
  "ghost" | "overlay" | "soft" | "outline"

  ghost: a bare icon button for rows and headers. overlay: a round glass button for photos (white heart, black glass in both themes). soft and outline: a chip for counts and labels.

• sizedefault "md"
  "sm" | "md" | "lg"

  Icon only: 32 / 40 / 48px (the overlay 32 / 36 / 44px) with a 16 / 20 / 22px heart; md grows to 44px on touch and the rest get a 44px hit area. Chips take the button heights.

• radiusdefault "full"
  "none" | "sm" | "md" | "lg" | "full"

  Corner shape, scaled per size like the button. full is a circle, or a pill for chips.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The on color. neutral fills black / white (white on photos); the classic red heart is danger. The chip tints use the tone's soft colors.

• colordefault ""
  string

  Any CSS color for the filled heart, the burst and the chip tint. Replaces the tone.

• icondefault "<Heart />"
  ReactNode

  Any lucide icon: ThumbsUp for a helpful vote, Bookmark for saved searches, Star. The on copy is drawn with fill-current.

• countdefault 0
  number

  The total including this person's vote, as the server knows it. The shown number moves by one right away when toggled and never goes below 0. Compact from 10.000 (12,4 K).

• showCountdefault false
  boolean

  Shows the count beside the icon; it rolls up or down when it changes and is described to screen readers.

• showLabeldefault false
  boolean

  Shows labels.save / labels.saved beside the icon. Both share one cell, so the chip never changes width. The accessible name stays constant (labels.name, or labels.save when no name is given) while aria-pressed flips.

• burstdefault true
  boolean

  A ring and particles when a person turns it on. Never on mount, on a prop change or under reduced motion.

• particleCountdefault 8
  number

  How many particles the burst throws, spread evenly around the heart with a fixed jitter.

• tooltipdefault true
  boolean

  Shows the action (labels.add / labels.remove) as a tooltip on hover and focus. Never on touch.

• hapticsdefault true
  boolean

  A light tick on touch when it turns on and an error buzz on rollback. Never from a mouse or on mount.

• disableddefault false
  boolean

  Dims the button and blocks it.

• localedefault ""
  string

  Formats the count (1.284 in ro-RO, 1,284 in en-US). Empty uses the UIProvider locale, then the browser's.

• labels
  Partial<FavoriteButtonLabels>

  Every string: name "Save" (the constant accessible name), add "Add to favorites", remove "Remove from favorites", save "Save", saved "Saved", error "Could not save. Try again.", count (n, formatted) => "128 saves". Pass only the keys you translate.

• classNames
  Partial<Record<"icon" | "burst" | "label" | "count", string>>

  Extra classes for the inner parts.

• typedefault "button"
  "button" | "submit" | "reset"

  Defaults to "button" so the heart never submits a surrounding form.

• onClick
  (event: MouseEvent<HTMLButtonElement>) => void

  Runs before the toggle; event.preventDefault() cancels it.

• className
  string

  Extra classes for the button, merged last.

Parts

FAQ

Used in

More React commerce components