Skip to content
flyingsalmon

Notice

The shell’s one persistent surface for a result with no visible home: one at a time, announced without moving focus, and always linked back to its subject.

Installation

npx shadcn@latest add @flyingsalmon/notice

Usage

import { AlertVariant } from '@/components/ui/alert'
import { Button } from '@/components/ui/button'
import { NoticeProvider, useNotice } from '@/components/ui/notice'

export function AppShell({ children }: { children: React.ReactNode }) {
  return <NoticeProvider>{children}</NoticeProvider>
}

export function SaveTripButton() {
  const { show } = useNotice()

  function saveTrip() {
    show({
      variant: AlertVariant.Success,
      title: 'Trip saved',
      subject: <a href="/trips/lisbon">View the trip</a>,
    })
  }

  return <Button onClick={saveTrip}>Save</Button>
}

Examples

Variants

The four alert variants. The icon carries the variant on a plain white card, and error is the one that interrupts a screen reader.

Replacement

Press both buttons in turn. A second notice swaps the content in place, with no exit and no enter, and the new text is announced again even when it reads the same.

Dismissing from the handle

Save the trip, then open it from the notice. show returns a handle, and the page uses it to take its own notice down once the trip it points at is on screen.

After a closed dialog

A dialog form closes on submit, so a server error has no inline home. Add a place and the planner fails on purpose: the error becomes a notice whose button reopens the form with what you typed.

Placed in an app shell

Save the trip. The notice lands below the page header and centres on the content beside the sidebar, so the title and actions stay in view while it shows. The shell sets --notice-offset-top and --notice-offset-left around the provider, and follows the sidebar as it collapses or becomes a strip.

Itinerary

Guidelines

When to use

  • For the result of a dialog form after it has closed and the item it changed is not on screen.
  • For a confirm-only action with nothing to update, such as a copied link.
  • For a result that arrives after the traveller has navigated away from where they acted.

When not to use

  • Use Alert for the result of a form that is still on screen. It goes in the form’s result slot, below the actions row.
  • Use Error state when a region failed to load. The region says so itself, with a retry.

Do and don’t

  • Do
    Give every notice a subject: a link to the item it is about, or a button that reopens the dialog with what the traveller typed.A message with no way back to its subject cannot be acted on, and the traveller has to hunt for what it meant.
  • Do
    Leave the notice on screen until the traveller follows its subject or dismisses it.It carries a result with no other home, so it stays until it is seen. A timer would take it from someone who looked away. That is what separates it from a toast.
  • Do
    Place the notice below the page header and centre it on the content area, beside the sidebar rather than across it.The notice stays until it is seen, so over the page header it would hide the screen’s title and actions for as long as it shows. Centred on the content, it reads as part of the page it reports on.
  • Don’t
    Stack notices. A new result replaces the one showing.One notice at a time keeps each result tied to the action that caused it. A pile has no order and no owner.
  • Don’t
    Show a notice about an item the traveller can already see.The item’s own state is the right home. A notice beside it says the same thing in a second place.

Accessibility

KeyDescription
TabReaches the subject, then the Dismiss button. The notice sits before your content in the document, so both come before the page, matching where the card appears.
EnterSpaceOn the subject, follows the link or runs its button. On Dismiss, closes the notice.
EscapeDoes nothing. The key stays with dialogs and menus.

The provider mounts two visually hidden live regions: role="status" for info, success, and warning, and role="alert" for error. Each show rewrites the matching region with the title, description, and subject text, so the same words are read again when the same result happens twice. Dismissal announces nothing.

Focus never moves to the notice: the control the traveller pressed keeps it. A route change clears nothing, because the registry knows no router. Returning focus after a dismissal is the app’s job.

API

NoticeProvider

Mount it once in the app shell: a second provider would give the page two notices that do not know about each other. It renders the live regions, the notice outlet, then your children. To keep the notice clear of your shell, set --notice-offset-top to the height of what stays above the content, such as a page header, and --notice-offset-left or --notice-offset-right to the width of a sidebar or panel, on any element around the provider. Each defaults to zero, the edge of the viewport. A shell with a sidebar maps the sidebar’s layout and its page header’s height onto these offsets, so the notice follows the sidebar as it collapses or becomes a strip.

PropTypeDefaultDescription
childrenReactNode–The app. Anything inside can call useNotice.

useNotice()

Returns show and dismiss. It throws outside a NoticeProvider.

PropTypeDefaultDescription
show(notice: NoticeInput) => NoticeHandle–Shows a notice, replacing any that is showing. The handle’s dismiss closes this notice only.
dismiss() => void–Closes whatever is showing, with the App reason.

NoticeInput

The object passed to show.

PropTypeDefaultDescription
variantAlertVariantRequiredInfo, Success, Warning, or Error.
titlestringRequiredWhat happened.
descriptionstring–One sentence of detail.
subjectNoticeSubjectRequiredA bare anchor or button. The notice places it under the description and styles it as a link with its focus ring.
onDismiss(reason: NoticeDismissReason) => void–Called when the notice goes: User for the Dismiss button, App for dismiss, Replaced when another notice takes over.

  • Alert

    The in-flow message for a result that has a surface on screen.
  • Dialog

    Closes on submit, which is when a notice carries the error.
  • Error state

    The failed state of a region, with a retry.
  • Principles

    The feedback rule behind where a result appears.