NotificationNudge
A small popover that points at a button with news, once: a title, a line, an action and Later, opening by itself without taking focus.
import { NotificationNudge } from "@butteryui/react";Demo
Opens below the bell: 2 customers asked about delivery
When to use it
Use it for
- Pointing out something new behind a button, such as replies waiting behind the notifications bell
- A one-time hint about a control people haven't found
Not for
- Something that just happened because of what someone did: use a toast
- A suggestion that stays until it's done: use Banner or RecommendationCard
Examples
Delivery questions
A nudge on the notifications bell that opens by itself on the first visit only, and from the bell after that.
New export
A nudge kept open in state, opened when the page decides, here from a button, pointing at a new export button.
Nothing exported yet
Top bar bell
An app's top row: a search, then the bell with its nudge and the account; reading the messages clears the dot.
2 unread messages
Variants and states
Opens by itself, once
It doesn't take focus: press Tab on the bell to go into it. Later, the action, Escape or a press outside closes it.
Props
NotificationNudge
| Prop | Type | Default | Description |
|---|---|---|---|
ref | Ref<HTMLDivElement> | The nudge's panel, while it's open. | |
childrenrequired | ReactElement | The button it points at, usually an IconButton with dot. Pressing it opens and closes the nudge. | |
titlerequired | string | What's new, in title-sm. It names the nudge and is announced when it opens by itself. | |
description | ReactNode | A line more about it, in body-sm. | |
actionrequired | GuidanceAction | What to do about it, as a small primary button. | |
laterLabel | string | "Later" | The ghost button that puts it off. Defaults to "Later". |
onLater | (() => void) | Called when Later is pressed. | |
storageKey | string | It opens by itself once per key, and not again once it has closed. Without one it opens by itself on every visit. | |
opensItself | boolean | true | Whether it may open by itself once its button is in view. Defaults to true. Pass false where it would
cover something people need, such as a page header's actions under its button: one that opened by itself
closes, still unseen, and it opens by itself once this is true again. |
open | boolean | Whether it's open, when you control it. | |
defaultOpen | boolean | false | Whether it starts open when uncontrolled, without taking focus. Defaults to false; with storageKey
it opens by itself once in view. |
onOpenChange | ((open: boolean) => void) | Called when it opens or closes. | |
className | string | Classes for the nudge's body, the element that carries data-bt="NotificationNudge". | |
style | CSSProperties | Inline styles for the same element. | |
side | "top" | "right" | "bottom" | "left" | "bottom" | The side of the button it opens on. Defaults to "bottom". |
align | "start" | "center" | "end" | "end" | Which edge of the button it lines up with. Defaults to "end". |
GuidanceAction
What a guidance part points to: a label, and where it goes or what it does.
| Field | Type | Default | Description |
|---|---|---|---|
labelrequired | string | What it says, such as "Connect a label printer". | |
href | string | Makes it a link to this page. | |
onClick | ((event: MouseEvent<HTMLElement>) => void) | Runs when it's pressed, or as its link is followed, where a router can take over. |
Accessibility
It opens by itself once its button is in view, no modal dialog is open and opensItself isn't false, without moving focus, and its title is announced as a status. It's a non-modal dialog named by its title. Tab from its button goes into it, Shift+Tab from its first button goes back, and Tab from its last goes on to what follows the button. Escape, Later, the action or a press outside closes it, and it doesn't open by itself again for the same storageKey.
| Keys | What they do |
|---|---|
| Enter or Space | Opens or closes the nudge from its button, or presses the action or Later, which close it |
| Tab | Goes from its button into the open nudge, and from the nudge's last button on to what follows its button |
| Shift+Tab | Goes from the nudge's first button back to its button |
| Escape | Closes the nudge and puts focus back on its button |
Motion
It appears with a `Presence` preset and leaves faster than it came, in about 60% of the time.
With reduced motion: It fades in and out in 100ms without growing.
Layout
It opens 8px from its button, below it and lined up with its end edge by default, as a popover at most 280px wide and never wider than the room beside the button, kept inside the window without covering the button. Its title and line wrap, its two 28px buttons wrap onto a new line when they don't fit, and the button it points at keeps its own size and hit area.
Related
See it in the roastery demo.