Composables
useGdNotify
The notification queue. Raise a toast from anywhere — a watcher, a poll, a store — without knowing where toasts live. The tone decides whether it fades or waits to be dismissed.
Anatomy
Code
const { notify } = useGdNotify()
notify('Parcel saved')
notify('Could not reach the council register', { tone: 'danger', action: 'Retry', onAction: retry })The tone decides the behaviour
- Success and info are transient — five seconds. They confirm what the user already asked for, so missing one costs nothing.
- Caution and danger are STICKY, with a dismiss affordance the transient forms never show. An error that auto-dismisses is an error you have decided the user may miss.
- Four on screen at once, at most. A fuller queue drops its oldest TRANSIENT notice first — never a sticky one, because dropping an unread error to make room for a save confirmation would invert the whole policy.
- Client-side only. A notification raised during server render has no one to see it, and callbacks cannot cross the payload. Call it from handlers, watchers and polls — which is where notifications come from anyway.
- One line, not a paragraph. Something needing a paragraph wants an alert, which stays on the page beside the thing it is about.
API
Returns
Props
PropTypeDefault
noticesRef<GdNotice[]>—The queue. `GdToastHost` reads it; almost nothing else should need to.
notify(message: string, options?: GdNotifyOptions) => number—Raise one. Returns its id, so a long-running caller can dismiss it later.
dismiss(id: number) => void—Remove one by id.
GdNotifyOptions
Props
PropTypeDefault
tone"success" | "info" | "caution" | "danger""success"Also decides the behaviour: success and info are transient, caution and danger are sticky.
actionstring—The single action affordance — "Retry", "View". One only.
onAction() => void—What the action does. A callback cannot cross the SSR payload, which is part of why this is a client-side API.
stickyboolean—Force the behaviour either way. The default is the policy, so overriding it should be a decision rather than a habit.