Configuration

NextToast has two layers of control:Global configPer-toast optionsGlobal config changes how the renderer behaves (position, colors, close button, max visible). Per-toast options control an individual toast (duration, dismissible, description, action).

Global config

Use toast.setConfig() to update the renderer configuration at runtime. You typically set global config in UI controls (like a settings page) or in docs demos. Global config updates immediately and affects toasts going forward.

When to use global config

• Choose a position that works across your whole product.
• Enable rich colors if your design system supports stronger UI states.
• Enable a close button if toasts can remain visible longer.
• Limit maxVisible to reduce noise when many toasts fire quickly.

position

Controls where the toast stack is anchored. Use top positions for immediate visibility, bottom positions for non-blocking feedback in dashboard-style UIs.

Available positions:top-left, top-center, top-right, bottom-left, bottom-center, bottom-right

Recommendations

• Dashboard apps Use bottom-right to keep toasts out of the main content area.
• Marketing / content sites Use top-center for visibility without covering primary actions.

richColors

When enabled, toast variants use stronger backgrounds and more vivid state colors. This is useful when you want higher contrast feedback, or when your UI is already colorful.

Guidelines

• Use rich colors when toasts should be highly scannable at a glance.
• Turn it off for minimal UIs where subtle borders and text are preferred.
• Avoid mixing multiple attention-heavy UI elements (alerts, banners, rich toasts) in the same view.

closeButton

Shows a close icon on each toast (when the toast is dismissible). Enable this when your toasts may stay visible long enough that users benefit from manual dismissal.

Notes

• Close button only appears when dismissible is true.
• For short durations (2–4 seconds), the close button often isn’t necessary.

maxVisible

Limits how many toasts can be visible at once. When more toasts are added, overflow is dismissed. This prevents UI clutter during rapid sequences of events.

Recommendations

• Most apps feel good at 3–5.
• Use 2 for minimal interfaces or when toasts are frequent.
• Use higher values only if your toasts are rare and non-intrusive.

Per-toast options

Per-toast options apply to a single toast. These are passed as the second argument to toast calls. Use them when one toast needs different behavior than your global defaults.

duration

Duration is in milliseconds. A good baseline:

• Success / Info: 2000–4000ms
• Warning / Error: 4000–6000ms
• Loading: use Infinity or toast.loading

dismissible

If dismissible is false, the user cannot manually close the toast. This is most useful for loading flows or required messages. Prefer short durations over non-dismissible toasts when possible.

Default config pattern

In production apps, set your global config once (position, maxVisible, etc.) and then only override per-toast options when necessary. This keeps behavior consistent across your UI.

Render Configure

Next

Continue to Examples for copy-paste flows like promise handling, long-running updates, and reusable patterns.