In progress

Toast Notification

A Toast Notification is a short-lived, floating message that appears above the content to confirm an action or display a temporary system status before dismissing automatically.

Code example

import BrowserOnly from '@docusaurus/BrowserOnly';
import {
  Button,
  ToastNotifications,
  ToastProvider,
  useToast,
  type ToastNotificationProps,
} from '@yleisradio/yds-components-react';

export type ToastProps = ToastNotificationProps & { buttonText?: string };

const ToastButton = ({ buttonText, ...props }: ToastProps) => {
  const toast = useToast();
  return <Button onClick={() => toast({ ...props })}>{buttonText ?? 'Toast!'}</Button>;
};

export const Toast = (props: ToastProps) => {
  return (
    <BrowserOnly>
      {() => (
        <ToastProvider>
          <ToastButton {...props} />
          <ToastNotifications />
        </ToastProvider>
      )}
    </BrowserOnly>
  );
};

Code example

const toast = useToast();
toast({ level: 'success', duration: 3000, children: 'This is a toast notification' })}

Why to use

Toast Notifications provide lightweight, non-blocking feedback. They acknowledge actions (save, copy, submit), report transient issues (temporary connection loss), or inform about short status changes without forcing user interaction or shifting focus away from the current task.

When to use

Use a Toast when the message is brief, non-critical, and not tied to a specific element on the page. Toasts float over the UI and disappear automatically.

Use for quick confirmations and short status updates that do not require user action.
Prefer in mobile UIs; on large viewports, ensure placement and contrast make the toast noticeable.
Keep copy concise and scannable; one clear message per toast.
Provide a manual close when the message may take longer to read or the user wants to dismiss it early.
Use either the info level alone for feedback or all four levels (info, success, warning, error) to convey different message types consistently.

Don’t

Don’t use for critical or persistent information — use Inline Notification (local to content) or Notification Banner (page/service-wide) instead.
Don’t tie the message to a specific field or control — use Inline Notification in that case.
Don’t spam repeating messages.
Don’t shift focus to the toast; it should not interrupt the user’s flow.

Differences between Notification Types

Type	Purpose	Placement	Use case
Banner Notification	A notification covering the entire view or service (e.g., maintenance, error state).	Fixed, below the header.	“Maintenance in progress”
Inline Notification	A local notification within content or a form (e.g., field error).	Embedded in content.	“This field is required”
Toast Notification	A short-lived, automatically disappearing feedback message (e.g., save confirmation).	Floating near the bottom of the screen, sliding in and out smoothly.	“Saved successfully”

Anatomy

TextArea anatomy

Icon – Icon indicating the message level (info, success, warning, error).
Body – Main message content.
Action – Main action guiding the user’s next step.

Key ToastNotification Props

Toasts are triggered with the toast function from useToast(). Pass a props object matching ToastNotificationProps.

level

Sets semantic and visual styling (icon + colors).

Value	Example	Description
`info`		Neutral informational context.
`success`		Positive confirmation.
`warning`		Caution, needs attention soon.
`error`		Critical or blocking issue.

Code example

toast({ level: 'info', children: 'General information' });
toast({ level: 'success', children: 'Changes saved' });
toast({ level: 'warning', children: 'Unstable connection' });
toast({ level: 'error', children: 'Upload failed' });

children (message)

Main textual content. Keep it short (typically one sentence).

Type	Example	Description
`ReactNode`		Message body displayed inside toast.

Code example

toast({ level: 'success', children: 'Profile updated' });

icon

Override default icon for a given level.

Type	Example	Description
`ReactNode`		Replaces semantic default icon.

Code example

import { Star } from '@yleisradio/yds-icons-react';
toast({ level: 'info', icon: <Star />, children: 'Favorited' });

hideIcon

Suppress level icon.

Type	Example	Description
`boolean`		Removes icon for minimal style.

Code example

toast({ level: 'info', hideIcon: true, children: 'Plain text toast' });

hideCloseButton

Omits manual close button. When hideCloseButton is true and no duration is given, a default auto-dismiss of 3000ms is applied.

Type	Example	Description
`boolean`		Auto-dismiss only; no manual close.

Code example

// Auto dismiss after default 3000ms
toast({ level: 'success', hideCloseButton: true, children: 'Saved successfully' });

duration

Total visible time (ms). If provided AND hideCloseButton is false, a timer bar is shown. If hideCloseButton is true, duration overrides the default 3000ms but no timer bar appears.

Type	Example	Description
`number`		Time before auto-dismiss.

Code example

// With timer bar (close button visible)
toast({ level: 'info', duration: 5000, children: 'Will hide after 5s' });

// Without close button (no timer bar)
toast({ level: 'info', hideCloseButton: true, duration: 6000, children: 'Auto hides after 6s' });

closeText

Custom text label for the close button if no closeIcon is supplied. Defaults to "Sulje".

Type	Example	Description
`string`		Localized close label.

Code example

toast({ level: 'info', closeText: 'Dismiss', children: 'Message sent' });

Behavior

Appears floating above content, typically near the bottom in Yle services.
Auto-dismisses after its defined duration.
Clicking the toast with timer bar removes the timer and keeps it visible until manually closed.
Conveys one concise message with an optional icon and Close button.
Does not move focus or interrupt the user’s ongoing task.
For critical or persistent information, surface the same message elsewhere (e.g., inline error, banner, or message log).

Animation behavior

Toast notification appears from the bottom of viewport.
Duration timer decreases from right to left.

Action	Duration	Easing
Appear	`m` / `250ms`	`dec` / `cubic-bezier(0.17, 0.84, 0.44, 1)`
Timer bar	`duration` (default: 3000 ms)	`lin` / `linear`
Exit	`m` / `250ms`	`dec` / `cubic-bezier(0.17, 0.84, 0.44, 1)`

Accessibility

Uses a live region to be announced by assistive tech: aria-live="polite".
Ensures sufficient color contrast per WCAG 2.1 – 1.4.3 (AA) and avoids color-only meaning (1.3.1).
Visible focus and full keyboard operability for the Close control (2.1.1 Keyboard, 2.4.7 Focus Visible).
Shows long enough to read (at least 3 s); provide a Close control and/or a way to pause auto-dismiss when necessary (2.2.2 Pause, Stop, Hide).
Critical information is also available elsewhere (e.g., inline error) so the message is not lost (4.1.3 Status Messages).

Implementation examples

Basic toast (manual close)

Code example

const TriggerBasicToastInline = () => {
  const toast = useToast();
  return (
    <Button
      text="Show success toast"
      onClick={() => toast({ level: 'success', children: 'Changes saved' })}
    />
  );
};

<ToastProvider>
  <TriggerBasicToastInline />
  <ToastNotifications />
</ToastProvider>

Auto dismiss (no close button)

Code example

const TriggerAutoDismissToast = () => {
  const toast = useToast();
  return (
    <Button
      text="Show auto toast"
      onClick={() => toast({ level: 'info', hideIcon: true, hideCloseButton: true, children: 'Copied to clipboard' })}
    />
  );
};

<ToastProvider>
  <TriggerAutoDismissToast />
  <ToastNotifications />
</ToastProvider>

With timer bar (duration + close)

Code example

const TriggerTimedToast = () => {
  const toast = useToast();
  return (
    <Button
      text="Show timed toast"
      onClick={() => toast({ level: 'warning', duration: 5000, children: 'Network unstable' })}
    />
  );
};

<ToastProvider>
  <TriggerTimedToast />
  <ToastNotifications />
</ToastProvider>

API Reference

Props

The ToastNotification component accepts the following props when using the toast function from useToast():

Prop	Type	Required	Default
`icon`	`ReactNode`	No	—
`level`	`NotificationLevel`	Yes	—
`duration`	`number`	No	—
`hideCloseButton`	`boolean`	No	—
`children`	`ReactNode`	No	—
`hideIcon`	`boolean`	No	—

Type Definitions

export type NotificationLevel = 'info' | 'success' | 'warning' | 'error';

export type ToastNotificationProps = {
  icon?: ReactNode;
  level: NotificationLevel;
  duration?: number;
  hideCloseButton?: boolean;
  children?: ReactNode;
  hideIcon?: boolean;
};

Notification – Inline contextual messages that persist until state changes.
BannerNotification – Page/service-wide announcements below the header.

Why to use​

When to use​

Differences between Notification Types​

Anatomy​

Key ToastNotification Props​

level​

children (message)​

icon​

hideIcon​

hideCloseButton​

duration​

closeText​

Behavior​

Animation behavior​

Accessibility​

Implementation examples​

Basic toast (manual close)​

Auto dismiss (no close button)​

With timer bar (duration + close)​

API Reference​

Props​

Type Definitions​

Related Components​

Why to use

When to use

Differences between Notification Types

Anatomy

Key ToastNotification Props

level

children (message)

icon

hideIcon

hideCloseButton

duration

closeText

Behavior

Animation behavior

Accessibility

Implementation examples

Basic toast (manual close)

Auto dismiss (no close button)

With timer bar (duration + close)

API Reference

Props

Type Definitions

Related Components