# Featured Card

Feature one offer or status in a sidebar or a panel, such as the storage a team has used, with its progress and a pair of link actions.

Used space with a progress bar

[Complete TSX file](/examples/featured-card/default.tsx)

```tsx
"use client";

import { FeaturedCard } from "@/siteplane/components/featured-card";

// The width of a card in the footer of a 256 px sidebar.
export default function Example() {
  return (
    <div className="w-full max-w-60">
      <FeaturedCard
        confirmLabel="Upgrade plan"
        description="Your team has used 80% of its storage. Upgrade for more space."
        onConfirm={() => undefined}
        onDismiss={() => undefined}
        progress={80}
        title="Used space"
      />
    </div>
  );
}
```

## Installation

Complete [one-time setup](/docs/installation/) first.

```bash
pnpm dlx shadcn@4.18.0 add @siteplane/featured-card
```

With npm: `npx shadcn@4.18.0 add @siteplane/featured-card`. [Registry JSON](/registry/featured-card.json) lists source files and dependencies.

## Usage

```tsx
import { FeaturedCard } from "@/siteplane/components/featured-card";

<FeaturedCard
  confirmLabel="Upgrade plan"
  description="Your team has used 80% of its storage."
  onConfirm={() => undefined}
  onDismiss={() => undefined}
  progress={80}
  title="Used space"
/>;
```

## Parts

A Featured Card shows its `title` over its `description`, a progress indicator, and the links Dismiss and the offer's own action. It is a [Card](/docs/components/card/) in the compact density: 16 px inside its edge, with the parts 16 px apart. The title is 14 px on a 20 px line in the label weight, and the description is 14 px tertiary text 4 px below it. Long values wrap. A card in the footer of a [Sidebar](/docs/components/sidebar/) takes the width of the sidebar, 240 px inside its 8 px insets; the examples on this page have that width.

## Progress

`progress` takes a value from 0 to 100, and a value outside it is clamped. `indicator="bar"`, the default, draws a [Progress](/docs/components/progress/) bar under the text. `indicator="circle"` draws a 64 px ring with the figure in it, 12 px above the text, so the title gets the whole line. Without `progress` the card shows its text and its actions only.

Used space with a progress ring

[Complete TSX file](/examples/featured-card/circle.tsx)

```tsx
"use client";

import { FeaturedCard } from "@/siteplane/components/featured-card";

export default function Example() {
  return (
    <div className="w-full max-w-60">
      <FeaturedCard
        confirmLabel="Upgrade plan"
        description="Your team has used 80% of its storage. Upgrade for more space."
        indicator="circle"
        onConfirm={() => undefined}
        onDismiss={() => undefined}
        progress={80}
        title="Used space"
      />
    </div>
  );
}
```

## Dismiss and confirm

`onDismiss` shows a close button 4 px inside the top-end corner and the Dismiss link, and both call it; a title that leads the card ends before the close button. The card does not remove itself: remove it in `onDismiss`, and remember the choice where it should last, such as until the next release. `confirmLabel` shows the offer's link in the accent color, 12 px after Dismiss, and `onConfirm` runs when it is pressed. Pass neither for a card that only informs.

A card that is removed when it is dismissed

[Complete TSX file](/examples/featured-card/dismiss.tsx)

```tsx
"use client";

import { useState } from "react";
import { Button } from "@/siteplane/components/button";
import { FeaturedCard } from "@/siteplane/components/featured-card";

// The application removes the card when it is dismissed and decides whether
// it comes back, for example after the next release.
export default function Example() {
  const [shown, setShown] = useState(true);
  return (
    <div className="flex w-full max-w-60 flex-col items-start gap-3">
      {shown ? (
        <FeaturedCard
          confirmLabel="Read the changes"
          description="Shared views and a faster search are here."
          onConfirm={() => undefined}
          onDismiss={() => setShown(false)}
          title="What's new in 2.4"
        />
      ) : (
        <Button onClick={() => setShown(true)} variant="link">
          Show the card again
        </Button>
      )}
    </div>
  );
}
```

## Accessibility

The bar and the ring are progress bars named by `progressLabel`, or by the title when it is plain text, and screen readers hear their value. The close button is a [Close Button](/docs/components/button/#close-button) named `closeLabel`, “Close” by default; it is the card's last part in the document, so the keyboard reaches it after the links, as it reaches the close of a dialog or a notification last. When the close button or Dismiss has the focus, the focus moves to the next element after the card before `onDismiss` runs, so it does not fall back to the page when the card is removed. Dismiss and the confirm action are link [Buttons](/docs/components/button/) and take the keyboard focus outline. The title is a paragraph, not a heading, so the card adds nothing to the document outline.

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| FeaturedCard.title | ReactNode | required | The title, one short line such as “Used space”, in the label weight. |
| FeaturedCard.description | ReactNode | unset | The text under the title, in the tertiary text color. |
| FeaturedCard.progress | number | unset | The completion from 0 to 100, clamped to that range. Without it the card shows no indicator. |
| FeaturedCard.indicator | "bar" \| "circle" | "bar" | bar draws a progress bar under the text, circle a 64 px ring with the figure in it above the text. |
| FeaturedCard.progressLabel | string | the title, when it is plain text | The accessible name of the progress bar or ring. |
| FeaturedCard.confirmLabel | ReactNode | unset | The label of the offer's link, such as “Upgrade plan”, in the accent color. Without it the card shows no confirm action. |
| FeaturedCard.onConfirm | () => void | unset | Called when the confirm action is pressed. |
| FeaturedCard.onDismiss | () => void | unset | Shows the close button and the Dismiss link and is called by both. Without it the card shows neither. |
| FeaturedCard.dismissLabel | ReactNode | Dismiss | The label of the dismiss link. |
| FeaturedCard.closeLabel | string | Close | The accessible name of the close button. |
`FeaturedCardProps` extends the props of a `div`, except `children` and `title`,
and accepts a ref; `className` and the other props reach the Card. The root
carries `data-indicator` (`bar` or `circle`, while the card shows progress) and
`data-dismissible`, and its parts the slots `featured-card-lead`,
`featured-card-text`, `featured-card-title`, `featured-card-description` and
`featured-card-actions`. The type `FeaturedCardIndicator` is exported. The
card's inset follows the Card tokens, such as `--sp-rw-card-inset`
([Theming](/docs/customization/theming/#shared-dimensions)).

[Read the installed source](/source/featured-card).

## Usage notes

Show one Featured Card at a time, in the footer of a sidebar or at the side of a settings page, for something people can act on now: storage that runs out, a trial that ends, a new release. For a message that concerns the whole page, use an [Alert](/docs/components/alert/), and for a passing confirmation a [Toast](/docs/components/toast/).

Keep the title to one short line and the description to one or two sentences: in a sidebar the card is narrow, and a long text pushes the content below it out of view.
