Siteplane UI

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.

Markdown
"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

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

Complete the one-time setup first. Registry JSON lists source files and dependencies.

Usage

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 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 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 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.

"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.

"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 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 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

Component properties
PropTypeDefaultDescription
FeaturedCard.titleReactNoderequiredThe title, one short line such as “Used space”, in the label weight.
FeaturedCard.descriptionReactNodeunsetThe text under the title, in the tertiary text color.
FeaturedCard.progressnumberunsetThe 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.progressLabelstringthe title, when it is plain textThe accessible name of the progress bar or ring.
FeaturedCard.confirmLabelReactNodeunsetThe label of the offer's link, such as “Upgrade plan”, in the accent color. Without it the card shows no confirm action.
FeaturedCard.onConfirm() => voidunsetCalled when the confirm action is pressed.
FeaturedCard.onDismiss() => voidunsetShows the close button and the Dismiss link and is called by both. Without it the card shows neither.
FeaturedCard.dismissLabelReactNodeDismissThe label of the dismiss link.
FeaturedCard.closeLabelstringCloseThe 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).

Read the installed source.

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, and for a passing confirmation a 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.