Toasts

NextToast exposes a small, consistent API. Most methods accept a message and optional options like description, duration, dismissible, and action.

Basic notifications

Use these for straightforward user feedback. Keep titles short and avoid repeating UI context. For example, prefer Saved over Settings saved successfully if the action is already obvious.

toast.message

Neutral message toast. Best for low-priority feedback that should not steal attention.

toast.success

Use for completed actions: save, create, update, publish. Keep it short and affirmative.

toast.info

Use for informational updates: new version available, background jobs started, sync scheduled.

toast.warning

Use for recoverable problems: missing configuration, partial validation, limited access. Provide guidance in description when possible.

toast.error

Use for failed actions. Prefer actionable error text: what failed and what to do next.

Common options

description

Use description to add a second line of detail. This is the best place for small guidance like which setting to change, why an action failed, or what happens next.

duration

Duration is in milliseconds. Use shorter durations for success/info and longer durations for warning/error. For loading states, prefer an infinite toast and update it later.

dismissible

Set dismissible to false when the toast should not be manually dismissed (usually for loading or required flows). Use sparingly.

Action button

Use action for quick, reversible operations like Undo, Retry, or View. Keep the label short and the behavior safe.

Confirm

toast.confirm is useful for destructive actions when you want a lightweight confirmation without opening a modal. Keep the message specific.

Loading and update

Use toast.loading when an operation has unknown duration. It returns an id. Later you can toast.update the same toast to success/error.

Promise

toast.promise is the simplest way to handle async flows. It shows a loading toast, then swaps to success or error automatically.

Custom

Use toast.custom when you need complete control over layout and interactions. Keep it lightweight: short text, one primary action, optional dismiss.

Dismiss

Dismiss a single toast by id, or clear everything with toast.dismissAll(). This is useful when navigating between screens or replacing stale messages.

Dismiss by id

Guidelines

• Prefer toast.promise for async work; it reduces boilerplate and keeps state consistent.
• Keep titles short. Use description for details, next steps, or context.
• Avoid stacking repeated errors. Consider toast.dismissAll() before showing a critical toast.
• Use confirm for destructive actions when a modal would be too heavy.

API References

Next

Continue to Configuration to learn how to set global behavior like position, rich colors, close button, and max visible.