Celebrate

A small moment of celebration for something the person finished: confetti bursts from a badge with the message ("List cleared") and screen readers hear the message once. The confetti stays inside Celebrate's own box and never flies over what is around it: give it room with layout classes (h-24 w-full) for a wider burst. The message waits about 1.5 s to leave time for the triggering control's announcement; this does not detect when a screen reader finishes speaking. With reduced motion nothing flies: the badge only fades in. Put it where the eye already is, such as at the end of the list that was just cleared.

Install

import { Celebrate } from "@/components/ouro/celebrate/celebrate";

Example

<Celebrate show={items.every((item) => item.checked)} message="List cleared" />

Usage

Under OuroProvider's quiet, for people who want less, only the message shows and is heard: no confetti.

While the moment lasts, the root carries data-celebrate, so a checker or a test can find it.

Use instead when

• Use toast() instead to confirm an everyday action (saved, sent), and Alert for a message that should stay.

Props

Type: CelebrateProps.

cap

Type: CelebrateCap | readonly CelebrateCap[]

How often the confetti may burst: at most times times per day, week, 30-day month or ever, counted in localStorage under capKey (or the cap's own key). Pass several to hold to all of them, such as once per conversation and three times a day across the app: cap={[{ times: 1, per: "ever", key: `cleared:${id}` }, { times: 3, per: "day", key: "celebrations" }]}. Past a cap the message still shows and is heard, with no confetti. Moment counts under the same keys, so the two can share a cap.

capKey

Type: string

The key a cap without its own key counts under, such as "list-cleared". Falls back to id.

className

Type: string

Layout only: placement (mx-auto, mt-4). Appearance classes warn in development.

hideMessage

Type: boolean

Speaks the message without showing the badge, for a screen that already says it. The confetti still bursts.

message (required)

Type: string

What was achieved, in a few words: "List cleared", "Steps done". Shown in a badge and spoken.

ref

Type: Ref<HTMLSpanElement>

Reaches the rendered element.

show (required)

Type: boolean

Whether the moment is happening. When it turns true, confetti bursts from the message and screen readers hear the message, once; set it back to false to clear it, and to true again for another burst.

Native attributes

Also accepts the attributes in React's HTMLAttributes (id, aria-*, event handlers), passed to the rendered element, except those named on this page.

Don't use

These are not props. Passing one fails the type check with the fix in the error, and in development a console message names the fix.

• active: Not a prop. Ouro UI uses show: <Celebrate show={done} message="…" />.
• children: Not a prop. The text is message: <Celebrate show={done} message="List cleared" />.
• open: Not a prop. Ouro UI uses show: <Celebrate show={done} message="…" />.

className is for layout only

Pass margins, width and grid placement (mt-4, w-full, col-span-2). Your classes always win over Ouro UI's: Celebrate merges className last with cn (tailwind-merge), so a class that conflicts with its own replaces it.^{layout-classes}

Appearance comes from props, not classes. In development, a class that sets appearance logs one warning per component instance, naming the prop to use instead. A class sets appearance when, after its variants (hover:, sm:) and any ! are removed, it starts with bg-, text-, border-, rounded-, shadow-, font-, ring-, from-, via-, to-, fill- or stroke-, or is border, rounded, shadow or ring, or has a dark: variant. Text wrapping, overflow and table layout classes (text-wrap, text-ellipsis, border-collapse) are layout and do not warn.

Alignment classes (text-center) warn too: set alignment on a parent element.

Types

CelebrateCap

One limit on how often Celebrate bursts: times per period, under key or the component's capKey.

interface CelebrateCap {
  times: number;
  per: CelebrationPeriod | (string & { 'Use "day", "week", "month" or "ever"': never });
  key?: string | undefined;
}