Loading…

Notification List

beta

Notifications resting as a receding deck that springs open into a list on hover, focus or toggle, with cards that slide out when dismissed or swiped and a count that rolls.

Feedback
1 file
2 npm packages
Accessibility notes
Animates with motion

Playground

Installation

The CLI installs number-flow as well, because this component imports it. Or copy everything in by hand.

$pnpm dlx @dowel-ui/cli add notification-list

npm packages installed: class-variance-authority, motion.

Usage

Imported from your own path — the file is yours, so this is an import like any other.

app/page.tsxTSX

import { NotificationList } from "@/components/ui/notification-list";

Examples

Every example the tests run, live and operable, side by side.

Default
Expanded
Plain
Live

API

Generated from the component's own types, so a prop cannot appear here without existing.

<NotificationList>

Prop	Type	Default
`announceDismiss` What the status region says after a dismissal.	`(item: NotificationListItem) => string`	`defaultAnnounce`
`defaultExpanded` Starts fanned out, as if the toggle had been pressed.	`boolean`	`false`
`defaultItems` The notifications at first render (uncontrolled).	`NotificationListItem[]`	`[]`
`depth` Cards visible in the collapsed deck, including the top one.	`number`	`3`
`dismissLabel` The dismiss button's name.	`(item: NotificationListItem) => string`	`defaultDismissLabel`
`emptyMessage` Shown when there is nothing left.	`ReactNode`	`"You're all caught up"`
`items` The notifications, newest first (controlled — remove dismissed ones in `onDismiss`).	`NotificationListItem[]`	—
`label` The header text, which also names the region.	`string`	`"Notifications"`
`onDismiss` Called when a notification is dismissed, by button or by swipe.	`(id: string, item: NotificationListItem) => void`	—
`swipeToDismiss` Lets a sideways drag dismiss a card. The × button always works.	`boolean`	`true`
`variant`	`"card" \| "plain"`	`"card"`

Plus every attribute of <section> except children, defaultValue.

Accessibility

A section named by its header label, containing a real list (ul, role=list) of every notification — the deck is presentation only, so collapsed cards stay in the accessibility tree, and moving keyboard focus into the list fans it open so nothing focusable is hidden. The header is a disclosure button (aria-expanded, aria-controls) named with the count ("Notifications, 3"), since the rolling digits are aria-hidden. Escape folds the deck. Every card has a dismiss button named "Dismiss <title>"; swiping is an optional extra, never the only way. When a dismissed card held focus, focus moves to the next card's button, else the previous, else the toggle, and a polite status region announces the dismissal (empty on first paint). Icons are aria-hidden, so put who or what in the title. Hover expansion is mouse-only. Under reduced motion the deck opens, closes and reflows instantly.

Quality

Measured from the source and its tests at build time.

All scores

10/10

checks passed

Tested — passes
axe assertion — passes
Keyboard tested — passes
Storybook examples — passes
Accessibility documented — passes
Semantic tokens only — passes
Motion from tokens — passes
className merged — passes
Visible focus — passes
No fixed widths — passes

Prop

Type

Default

announceDismiss

What the status region says after a dismissal.

(item: NotificationListItem) => string

defaultAnnounce

defaultExpanded

Starts fanned out, as if the toggle had been pressed.

boolean

false

defaultItems

The notifications at first render (uncontrolled).

NotificationListItem[]

[]

depth

Cards visible in the collapsed deck, including the top one.

number

3

dismissLabel

The dismiss button's name.

(item: NotificationListItem) => string

defaultDismissLabel

emptyMessage

Shown when there is nothing left.

ReactNode

"You're all caught up"

items

The notifications, newest first (controlled — remove dismissed ones in onDismiss).

NotificationListItem[]

—

label

The header text, which also names the region.

string

"Notifications"

onDismiss

Called when a notification is dismissed, by button or by swipe.

(id: string, item: NotificationListItem) => void

—

swipeToDismiss

Lets a sideways drag dismiss a card. The × button always works.

boolean

true

variant

"card" | "plain"

"card"