When to use a notification, how long it should stay, and what to put in it.
When to use
A notification is a card in a corner of the screen, with a title, a description, an optional status icon and its own buttons. It reports something the reader did not ask about, and closes itself after 4.5 seconds by default.
Use it when the event needs more than one line, when it happened on its own schedule (a background job finished, a teammate did something), or when the reader should be able to act on it without losing their place.
Use something else when
One line is enough. Use message: no title, no actions, centered at the top and gone in 3 seconds.
It belongs to part of the page, like a validation summary or a “this is staging” note. Use Alert, placed next to what it describes.
It has to be answered before the reader can go on. Use Modal. A notification can be ignored.
It is a list. Three notifications at once is a feed. Show the feed, and notify once.
Title and description
title says what happened. description adds the detail that identifies it, or what the reader can do. Both take any node, so the description can hold a link.
Write the title as what happened, with the subject in it: “Export finished”, not “Success”. The reader may see it seconds after the click that caused it.
Keep the description to a line or two. The card is 384px wide and grows downward, so a paragraph pushes the buttons out of view.
A title alone is fine. A description alone reads like a message in the wrong component.
Use title and actions, not message and btn. The old names are deprecated and log a warning.
Placement
placement takes top, topLeft, topRight (the default), bottom, bottomLeft or bottomRight.
Pick one for the product and keep it, so the reader learns where to look.
You can pass placement per call, but each placement keeps its own pile, and two piles are harder to follow.
The bottom corners are also where chat buttons and cookie banners sit. Check the corner is free.
In a right-to-left layout, Left and Right keep their meaning.
Under a fixed header, set the global top offset past the header's height instead of moving the cards to another corner.
Duration
duration is in seconds and defaults to 4.5. duration: 0 keeps the card open until the reader closes it or you call destroy(key).
A card with buttons should stay open. An Undo that disappears after 4.5 seconds punishes reading. Set duration: 0 whenever you set actions.
So should an error the reader has to act on or copy something from. Successes can close themselves, failures should not.
showProgress draws the countdown. It does nothing on a card with duration: 0.
pauseOnHover is on by default and stops the timer while the pointer is over the card. Keyboard focus does not pause it, so a card with a button should use duration: 0, not a longer duration.
If a card is hard to read in 4.5 seconds, keep it open. A longer timer is not the fix.
Buttons inside a card
actions takes any node and renders it under the content. It is where Undo, Retry or “View report” go.
One primary button, two buttons at most. The card is small and competes with whatever the reader is doing.
Close the card from the button yourself: give the call a key and call destroy(key) in the handler. A card that stays after its button is pressed looks broken.
onClick makes the whole card clickable. It does not close the card, and it also fires when a button inside is clicked, so use one or the other.
The card and its buttons are gone once it closes. Make sure what they lead to can be reached another way.
closable is on by default. Turn it off only on a card that closes itself.
Icon and type
There are four types: success, info, warning and error. Each sets an icon and its color. There is no loading type.
open() without a type shows no icon, which is where an icon of your own fits best.
icon: null does not remove the icon on a typed call. To show none, call open() without a type, or pass classNames: { icon: "hidden" }.
An icon you pass is not colored for you. Give it a color class yourself.
Do not use a type for decoration. A red card that is not an error teaches the reader to ignore red.
The icon and its color can both be missed. The title has to say what happened in words, since that is what every reader gets.
Keys, updates and stacking
key is what makes two calls one card. Without it, every call opens a new card.
Calling again with the same key updates the card in place and restarts its timer. Use it for a progress card, or to turn a failure into a success after a retry.
Give a key to any card you might open twice or close later. destroy() with no key closes every card.
maxCount caps the number of cards and drops the oldest, even before its timer ends.
stack takes a threshold (3 by default) and an offset (8). Past the threshold the cards collapse into a pile, and hovering any of them expands the pile and pauses them all.
If you need maxCount to stop a flood, fix the source: debounce the events, or count them in one keyed card.
Use the hook, not the static
notification.success(...) imported from antd renders outside your React tree, so it ignores the theme, locale and direction around it. In a dark app it opens a light card.
Use useNotification(). It returns the notification methods bound to AntuikitProvider, so there is no contextHolder to render.
Call it from an event handler or an effect, never during render.
Outside AntuikitProvider, the hook throws an error that names the provider.