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/noticeUsage
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.
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
- DoGive 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.
- DoLeave 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.
- DoPlace 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’tStack 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’tShow 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
| Key | Description |
|---|---|
| Tab | Reaches 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. |
| EnterSpace | On the subject, follows the link or runs its button. On Dismiss, closes the notice. |
| Escape | Does 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| children | ReactNode | – | The app. Anything inside can call useNotice. |
useNotice()
Returns show and dismiss. It throws outside a NoticeProvider.
| Prop | Type | Default | Description |
|---|---|---|---|
| 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.
| Prop | Type | Default | Description |
|---|---|---|---|
| variant | AlertVariant | Required | Info, Success, Warning, or Error. |
| title | string | Required | What happened. |
| description | string | – | One sentence of detail. |
| subject | NoticeSubject | Required | A 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. |