Toast Notification

ToastNotification displays a temporary, non-blocking message above the current interface. Use it for save confirmations, background results, undo actions, synchronization updates, and short-lived errors. Unlike Alert, it does not reserve space in the page or block the current workflow.

Basic usageCopy Anchor Link

import { ToastNotification } from '@mosmox/ui';

<ToastNotification variant="success" title="Changes saved">
  Your workspace is ready to share.
</ToastNotification>

The component is visible by default and automatically closes after five seconds. children accepts any React content, not only plain text.

VariantsCopy Anchor Link

variant controls the semantic accent, icon, default ARIA role, and light/dark palette:

<ToastNotification variant="neutral" title="Draft saved">No action is required.</ToastNotification>
<ToastNotification variant="info" title="Sync started">We are checking for updates.</ToastNotification>
<ToastNotification variant="success" title="File uploaded">The file is ready to use.</ToastNotification>
<ToastNotification variant="warning" title="Connection is unstable">Some changes may be delayed.</ToastNotification>
<ToastNotification variant="danger" title="Upload failed">Try again or review the error.</ToastNotification>

neutral has no default icon. info, success, warning, and danger use semantic icons. Use icon to replace the default icon with any React node. Warning and danger messages use role="alert" by default; other variants use role="status".

Actions and custom contentCopy Anchor Link

actions accepts any React content, so buttons, links, and custom controls can be placed inside the message. Use actionsLabel when the action group needs an accessible label.

<ToastNotification
  variant="danger"
  title="Upload failed"
  actionsLabel="Upload actions"
  actions={
    <>
      <Button size="sm" variant="outline">Retry</Button>
      <Button size="sm" variant="text">Dismiss</Button>
    </>
  }
>
  The file could not be uploaded.
</ToastNotification>

Rich custom contentCopy Anchor Link

No extra prop is required for complex content. children is a ReactNode, so a ToastNotification can contain an ActivityFeed, ProfileMenu, card, form, or several nested blocks. Use layout="stacked" for content that is taller than a short message and set duration={false} when the user needs time to interact with it.

import { ActivityFeed, Button, ToastNotification } from '@mosmox/ui';

const activity = [
  {
    key: 'deploy',
    title: 'Deployment completed',
    actor: 'Maya Chen',
    timestamp: '10:42',
    description: 'Version 2.4.0 is now running.',
    status: 'success' as const,
  },
  {
    key: 'comment',
    title: 'New comment on Project Atlas',
    actor: 'Alex Morgan',
    timestamp: '09:18',
    description: 'The onboarding flow is ready for review.',
  },
];

<ToastNotification
  duration={false}
  layout="stacked"
  title="Recent activity"
  actions={<Button size="sm" variant="outline">Open activity</Button>}
>
  <ActivityFeed
    aria-label="Recent activity in ToastNotification"
    items={activity}
    size="sm"
    variant="compact"
    showConnector
  />
</ToastNotification>;

The ToastNotification body grows with its children and remains constrained by the ToastNotification width. For large custom blocks, keep the content responsive with width: 100% and consider maxHeight on scrollable child components. Interactive child controls remain keyboard accessible; pauseOnHover and pauseOnFocus also work for the complete custom content area.

Light and dark themesCopy Anchor Link

theme="light" is the default. Use theme="dark" for the charcoal ToastNotification treatment. The semantic accent remains determined by variant, and action buttons use the light action treatment on the dark surface.

<ToastNotification theme="dark" variant="success" title="Deployment complete">
  Version 2.4.0 is now running in production.
</ToastNotification>

Sizes and layoutsCopy Anchor Link

The component supports three sizes:

• default — regular padding, typography, icon, and close control;
• sm — compact padding, typography, smaller icon, and smaller close control.
• lg — larger padding and typography for persistent, content-rich updates.

<ToastNotification size="default" title="Default notification">
  Regular density for most page-level feedback.
</ToastNotification>
<ToastNotification size="sm" title="Small notification">
  Compact density for dense toolbars and utility areas.
</ToastNotification>
<ToastNotification size="lg" title="Large update">
  Extra room for a persistent or content-rich update.
</ToastNotification>

layout="inline" is the default and keeps content compact. Use layout="stacked" for longer content or several actions.

Timing, progress, and dismissalCopy Anchor Link

duration is measured in milliseconds and defaults to 5000. Pass false to keep the message open until the user or application closes it. The timer pauses on hover and focus by default. Set progress={false} to hide the remaining-time bar.

<ToastNotification duration={8000} pauseOnHover={false} title="Longer message">
  This message remains visible for eight seconds.
</ToastNotification>

<ToastNotification duration={false} closable title="Persistent status">
  This stays open until the close button is pressed.
</ToastNotification>

<ToastNotification duration={5000} progress={false} title="No progress bar">
  The timer still closes the message, but its indicator is hidden.
</ToastNotification>

Set closable={false} to remove the close button. Customize its accessible label with closeLabel.

Persistent updates and notification behaviorCopy Anchor Link

ToastNotification also covers persistent notification-style updates. Use duration={false} to disable automatic dismissal, then add the optional avatar, badge, timestamp, unread, read, onRead, href, onClick, and loading props as needed. children and actions remain fully composable, so a persistent ToastNotification can contain the same rich content as a transient one.

function WorkspaceUpdate() {
  const [unread, setUnread] = useState(true);

  return (
    <ToastNotification
      duration={false}
      variant="info"
      title="New comment on Project Atlas"
      avatar={<Avatar name="Alex Morgan" size="sm" />}
      timestamp="2 minutes ago"
      unread={unread}
      read={!unread}
      onRead={() => setUnread(false)}
      onClick={() => setUnread(false)}
      actions={<Button size="sm" variant="outline">View comment</Button>}
    >
      Alex Morgan mentioned you in a project discussion.
    </ToastNotification>
  );
}

Use href when the whole message should navigate. Use loading for a non-dismissible in-progress update; pair it with duration={false} when it must remain until the application changes its state. ToastNotificationStack replaces a separate notification stack and keeps multiple messages in a non-overlapping list.

<ToastNotificationStack maxWidth={760} position="top-right">
  <ToastNotification duration={false} size="lg" variant="success" title="Deployment completed" timestamp="Today, 10:42">
    Version 2.4.0 is now running in production.
  </ToastNotification>
  <ToastNotification duration={false} variant="warning" title="Billing action required" loading>
    We are checking your payment details.
  </ToastNotification>
</ToastNotificationStack>

Toast Notification stacksCopy Anchor Link

Use ToastNotificationStack when several Toast Notification messages can be visible at the same time. It lays out its child messages as a non-overlapping list while each message keeps its own timer and close behavior.

<ToastNotificationStack position="bottom-right">
  <ToastNotification variant="success" title="Saved" duration={false}>Your changes are ready.</ToastNotification>
  <ToastNotification variant="info" title="Sync started" duration={false}>We are checking for updates.</ToastNotification>
</ToastNotificationStack>

The stack supports the same six viewport positions as ToastNotification.

Mini ToastCopy Anchor Link

MiniToast is a compact dark notification for short, single-line progress or action messages. It accepts a programmer-defined icon or image on the left, truncates long text with an ellipsis, and always provides an action button on the right. The default action is Cancel; pass actionLabel={null} with actionIcon for an icon-only action.

Programmatic APICopy Anchor Link

Use ToastNotificationProvider and useToastNotification when notifications must be triggered from services, mutations, or event handlers without rendering each toast at the call site.

<ToastNotificationProvider>
  <App />
</ToastNotificationProvider>

const { success, danger, closeAll } = useToastNotification();
success('Changes saved');
danger('Upload failed', { duration: false, title: 'Error' });
closeAll();

show(options) returns an id. Use close(id) or closeAll() to dismiss programmatic notifications. MiniToastProvider and useMiniToast expose the same show, close, and closeAll pattern for mini messages.

<MiniToast icon={<ImageIcon />} actionLabel="Cancel">
  Generating an image...
</MiniToast>

<MiniToast icon={<ImageIcon />} actionLabel="Undo" duration={10000}>
  Image generated
</MiniToast>

Set duration in milliseconds to show a circular seconds countdown and close automatically. Use MiniToastStack to render several mini messages without overlap in any of the six viewport positions.

The width prop controls the message width and defaults to 350 pixels. It also accepts CSS width values such as "18rem" or "min(320px, 100vw - 32px)".

Use size="sm" for a shorter variant with reduced padding, icon, button, and typography. The default is size="default".

Set showAction={false} to hide the action button and divider. This mode always uses a countdown: it defaults to 10 seconds, or uses the supplied duration value.

<MiniToast showAction={false}>Processing...</MiniToast>
<MiniToast showAction={false} duration={15000}>This closes in 15 seconds.</MiniToast>

Controlled and uncontrolled visibilityCopy Anchor Link

Use defaultOpen for initial uncontrolled visibility. Use open with onOpenChange when the parent owns the visible state. onClose is called when the ToastNotification is dismissed by its timer or close button.

function SaveToast() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button onClick={() => setOpen(true)}>Save</Button>
      <ToastNotification
        open={open}
        onOpenChange={setOpen}
        onClose={() => console.log('ToastNotification closed')}
        title="Changes saved"
      >
        Your changes are now available to the team.
      </ToastNotification>
    </>
  );
}

Position and accessibilityCopy Anchor Link

position is a viewport preset: top-left, top-center, top-right, bottom-left, bottom-center, or bottom-right. The default is bottom-right.

The root has aria-atomic="true". Use aria-label when the visible content does not provide a sufficient accessible name. The component selects role="alert" for warning and danger, and role="status" for other variants; pass role to override this when needed.

Custom colors and ConfigProvider radiusCopy Anchor Link

The default ToastNotification palette is independent from semantic ConfigProvider color tokens. Add a class or inline style for application-specific colors. Supported ToastNotification CSS variables are --mm-toast-background, --mm-toast-border, and --mm-toast-accent.

<ToastNotification className="project-toast" variant="neutral" title="Custom notification">
  This ToastNotification uses the application palette.
</ToastNotification>

.project-toast {
  --mm-toast-background: #17152b;
  --mm-toast-border: #3d3768;
  --mm-toast-accent: #a78bfa;
}

ToastNotification border radius comes from the shared --mm-radius-control token. Configure it for the whole component tree through ConfigProvider:

<ConfigProvider theme={{ radius: '12px' }}>
  <ToastNotification title="Rounded notification">
    The surface and icon radius use the provider token.
  </ToastNotification>
</ConfigProvider>

API referenceCopy Anchor Link