Toast

An individual toast notification.

Examples

Default

Saved successfully

Dismiss notification

<Toast {...args} onDismiss={() => {}} />

Error

Unable to save

Dismiss notification

<Toast {...args} onDismiss={() => {}} />

Success

Saved successfully

Dismiss notification

<Toast {...args} onDismiss={() => {}} />

Warning

Storage almost full

Dismiss notification

<Toast {...args} onDismiss={() => {}} />

With Viewport

InfoSuccessWarningError

function HookStory(): React.JSX.Element {
  const toast = useToast();

  return (
    <HStack gap={2}>
      <Button
        label="Info"
        onClick={() => toast({body: 'Saved successfully'})}
      />
      <Button
        label="Success"
        onClick={() => toast({body: 'Changes published', type: 'success'})}
      />
      <Button
        label="Warning"
        onClick={() => toast({body: 'Storage almost full', type: 'warning'})}
      />
      <Button
        label="Error"
        onClick={() => toast({body: 'Unable to save', type: 'error'})}
        variant="destructive"
      />
    </HStack>
  );
}

<ToastViewport>
  <HookStory />
</ToastViewport>

Auto Dismiss

Show auto-dismiss toast

function AutoDismissStory(): React.JSX.Element {
  const toast = useToast();
  return (
    <Button
      label="Show auto-dismiss toast"
      onClick={() =>
        toast({
          body: 'This will disappear in 3 seconds',
          autoHideDuration: 3000,
        })
      }
    />
  );
}

<ToastViewport>
  <AutoDismissStory />
</ToastViewport>

With End Content

Show with action

function WithEndContentStory(): React.JSX.Element {
  const toast = useToast();
  return (
    <Button
      label="Show with action"
      onClick={() =>
        toast({
          body: 'Item deleted',
          endContent: <Button label="Undo" size="sm" variant="onSolid" />,
        })
      }
    />
  );
}

<ToastViewport>
  <WithEndContentStory />
</ToastViewport>

With Primary Action

A new version is available

Update now

Dismiss notification

Your export is ready

Download

Dismiss notification

Storage almost full

Upgrade plan

Dismiss notification

Unable to save

Retry

Dismiss notification

<div style={{display: 'flex', flexDirection: 'column', gap: '1rem'}}>
  <Toast
    autoHideDuration={5000}
    body="A new version is available"
    endContent={<Button label="Update now" size="sm" variant="primary" />}
    isAutoHide={false}
    onDismiss={() => {}}
    type="info"
  />
  <Toast
    autoHideDuration={5000}
    body="Your export is ready"
    endContent={<Button label="Download" size="sm" variant="primary" />}
    isAutoHide={false}
    onDismiss={() => {}}
    type="success"
  />
  <Toast
    autoHideDuration={5000}
    body="Storage almost full"
    endContent={<Button label="Upgrade plan" size="sm" variant="primary" />}
    isAutoHide={false}
    onDismiss={() => {}}
    type="warning"
  />
  <Toast
    autoHideDuration={5000}
    body="Unable to save"
    endContent={<Button label="Retry" size="sm" variant="primary" />}
    isAutoHide={false}
    onDismiss={() => {}}
    type="error"
  />
</div>

Positions

topStarttopEndbottomStartbottomEnd

function PositionsStory(): React.JSX.Element {
  const [position, setPosition] = useState<ToastPosition>('bottomEnd');
  return (
    <ToastViewport position={position}>
      <PositionButtons onChangePosition={setPosition} position={position} />
    </ToastViewport>
  );
}

function PositionButtons({
  position,
  onChangePosition,
}: {
  onChangePosition: (p: ToastPosition) => void;
  position: ToastPosition;
}): React.JSX.Element {
  const toast = useToast();
  const positions: ToastPosition[] = [
    'topStart',
    'topEnd',
    'bottomStart',
    'bottomEnd',
  ];
  return (
    <HStack gap={2}>
      {positions.map(p => (
        <Button
          key={p}
          label={p}
          onClick={() => {
            onChangePosition(p);
            requestAnimationFrame(() => toast({body: `Position: ${p}`}));
          }}
          variant={p === position ? 'primary' : 'secondary'}
        />
      ))}
    </HStack>
  );
}

<PositionsStory />

API

Toast

An individual toast notification.

Prop	Type	Default	Description
autoHideDuration*	number	—	Auto-dismiss duration in milliseconds.
body*	ReactNode	—	Toast message content.
className	string	—	Additional CSS class names applied to the toast.
data-testid	string	—	Test ID applied to the toast.
endContent	ReactNode	—	Content rendered before the dismiss button.
isAutoHide*	boolean	—	Whether the toast auto-dismisses.
isExiting	boolean	false	Whether the toast is exiting.
isPaused	boolean	false	Whether the toast auto-dismiss timer is paused by its container.
onDismiss*	(reason: ToastDismissReason) => void	—	Called when the toast should be dismissed.
ref	Ref<HTMLDivElement>	—	Ref forwarded to the toast element.
style	CSSProperties	—	Inline styles applied to the toast.
type*	"error" | "info" | "success" | "warning"	—	Toast tone.

ToastViewport

Toast provider and viewport. Mount once near the app root to enable toast notifications. Components below this provider can call `useToast()` to show toasts.

Prop	Type	Default	Description
children	ReactNode	—	App content that should receive the toast context.
className	string	—	Additional CSS class names applied to the viewport.
data-testid	string	—	Test ID applied to the viewport.
inset	Readonly<ToastViewportInset>	—	Custom viewport inset.
isTopLayer	boolean	true	Whether to promote the viewport to the CSS top layer using popover.
maxVisible	number	5	Maximum visible toast count.
position	"bottomEnd" | "bottomStart" | "topEnd" | "topStart"	'bottomEnd'	Toast stack position.
ref	Ref<HTMLDivElement>	—	Ref forwarded to the viewport element.
style	CSSProperties	—	Inline styles applied to the viewport.