Toast

Toast는 사용자 액션에 대한 일시적인 피드백을 표시합니다. 화면 가장자리에 나타났다 일정 시간 후 자동으로 사라지며, 명령형 API(toast.success() 등)로 어디서든 손쉽게 실행할 수 있습니다.

디자인 규격: Toast 너비는360px으로 고정입니다. 360px 미만 화면에서는max-width: calc(100vw - 48px)으로 자동 축소됩니다.

Types

Positions

Promise

Async Support

Pure

React

Playground

Preview

defaultbottom-right

Type

Position

Options

toast('Event has been created', {
  description: 'Monday, January 3rd at 6:00 PM',
})

Types

Features

Action & Cancel

actioncancel과 로 인라인 버튼을 추가할 수 있습니다.

toast('File deleted', {
  action: { label: 'Undo', onClick: () => handleUndo() },
  cancel: { label: 'Dismiss', onClick: () => {} },
})

Promise

toast.promise()를 사용하면 비동기 처리의 로딩 → 성공/오류를 자동으로 전환합니다.

toast.promise(
  fetch('/api/save'),
  {
    loading: 'Saving...',
    success: 'Saved!',
    error: 'Failed to save',
  }
)

Close Button

closeButton로 토스트에 닫기 버튼을 표시합니다.

toast.info('Notification', {
  closeButton: true,
  description: 'You have 3 unread messages.',
})

Rich Colors

richColors를 Toaster에 설정하면 상태 토스트를 솔리드 배경으로 강조합니다.

<Toaster richColors />

toast.success('Saved!')  // solid green background
toast.error('Failed!')   // solid red background

Loading

toast.loading()은 스피너와 함께 계속 표시됩니다. 직접 닫거나toast.dismiss(id)로 제거할 수 있습니다.

const id = toast.loading('Processing...')
// Later:
toast.dismiss(id)

API

Component Structure

Toast— Pure React (Imperative API)

toast()Propstoast.success()toast.error()toast.warning()toast.info()toast.loading()toast.promise()toast.custom()toast.dismiss()<Toaster />Props

toast(message, options?)Props기본 토스트

toast.success(message, options?)성공 토스트

toast.error(message, options?)오류 토스트

toast.warning(message, options?)경고 토스트

toast.info(message, options?)정보 토스트

toast.loading(message, options?)로딩 토스트 (계속 표시)

toast.promise(promise, handlers)Promise 연동 토스트

toast.custom(render, options?)커스텀 JSX 토스트

toast.dismiss(id?)토스트 닫기 (id 생략 시 전체 닫기)

<Toaster />Props렌더링 프로바이더

Props

Toaster

position"bottom-right"

토스트 표시 위치

duration4000

number

자동 소멸 시간 (ms), 0이면 계속 표시

visibleToasts5

number

동시에 표시할 최대 토스트 수

closeButtonfalse

boolean

전체 토스트에 닫기 버튼 표시

richColorstrue

boolean

상태 색상을 솔리드 배경으로 강조, false면 틴트 배경으로 전환

expandfalse

boolean

항상 모든 토스트를 펼쳐서 표시

offset24

number

화면 가장자리로부터의 오프셋 (px)

gap8

number

토스트 간격 (px)

size"default"

"sm" | "default" | "lg"

토스트 크기

classNameundefined

string

컨테이너 추가 CSS 클래스

Name	Type	Default	Description
`position`	`"top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right"`	`"bottom-right"`	토스트 표시 위치
`duration`	`number`	`4000`	자동 소멸 시간 (ms), 0이면 계속 표시
`visibleToasts`	`number`	`5`	동시에 표시할 최대 토스트 수
`closeButton`	`boolean`	`false`	전체 토스트에 닫기 버튼 표시
`richColors`	`boolean`	`true`	상태 색상을 솔리드 배경으로 강조, false면 틴트 배경으로 전환
`expand`	`boolean`	`false`	항상 모든 토스트를 펼쳐서 표시
`offset`	`number`	`24`	화면 가장자리로부터의 오프셋 (px)
`gap`	`number`	`8`	토스트 간격 (px)
`size`	`"sm" \| "default" \| "lg"`	`"default"`	토스트 크기
`className`	`string`	`undefined`	컨테이너 추가 CSS 클래스

toast() Options

descriptionundefined

ReactNode

보조 설명 텍스트

duration4000

number

개별 자동 소멸 시간 (ms)

dismissibletrue

boolean

닫기 가능 여부

closeButtonfalse

boolean

닫기 버튼 표시

iconauto (by type)

ReactNode

커스텀 아이콘

actionundefined

{ label: string; onClick: () => void }

액션 버튼

cancelundefined

{ label: string; onClick: () => void }

취소 버튼

onDismissundefined

(toast) => void

닫힐 때의 콜백

onAutoCloseundefined

(toast) => void

자동 소멸 시의 콜백

idauto

string

토스트 식별자 (업데이트, dismiss 용)

classNameundefined

string

개별 토스트 추가 CSS 클래스

Name	Type	Default	Description
`description`	`ReactNode`	`undefined`	보조 설명 텍스트
`duration`	`number`	`4000`	개별 자동 소멸 시간 (ms)
`dismissible`	`boolean`	`true`	닫기 가능 여부
`closeButton`	`boolean`	`false`	닫기 버튼 표시
`icon`	`ReactNode`	`auto (by type)`	커스텀 아이콘
`action`	`{ label: string; onClick: () => void }`	`undefined`	액션 버튼
`cancel`	`{ label: string; onClick: () => void }`	`undefined`	취소 버튼
`onDismiss`	`(toast) => void`	`undefined`	닫힐 때의 콜백
`onAutoClose`	`(toast) => void`	`undefined`	자동 소멸 시의 콜백
`id`	`string`	`auto`	토스트 식별자 (업데이트, dismiss 용)
`className`	`string`	`undefined`	개별 토스트 추가 CSS 클래스

Code Recipes

Anatomy

Undo

Toast Root

토스트 전체 컨테이너

Icon

상태 아이콘

Message

메인 메시지

Description

보조 설명 텍스트

Action

액션 버튼

닫기 버튼

Best Practices

✓

권장

✓짧고 명확한 메시지 사용
✓상태에 맞는 type 사용
✓파괴적인 액션에는 Undo 액션 제공

지양

✕긴 텍스트나 폼을 토스트에 넣지 않기
✕사용자 확인이 필요한 경우 Modal/AlertModal 사용
✕영속적인 상태 알림에는 Alert 사용 (Toast는 일시적)
✕동시에 너무 많은 토스트를 표시하지 않기

Toast vs Alert

둘 다 사용자 알림에 사용되지만, 표시 지속성과 인터랙션이 다릅니다.

표시

Toast: 일시적으로 표시된 후 자동 소멸

Alert: 페이지 내 고정 (영속적)

트리거

Toast: 사용자 액션 후 피드백으로 표시

Alert: 페이지 로드 시 또는 상태 변화 시

콘텐츠

Toast: 짧은 메시지 (1~2줄)

Alert: 타이틀 + 설명 (리치)

닫기

Toast: 자동 소멸 (수초 후)

Alert: 수동 (closable) 또는 항상 표시

용도

Toast: 저장 완료, 복사 완료 등

Alert: 시스템 상태, 경고, 오류

ARIA

Toast: role="status" + aria-live

Alert: role="alert" / role="status"

특징	Toast	Alert
표시	일시적으로 표시된 후 자동 소멸	페이지 내 고정 (영속적)
트리거	사용자 액션 후	페이지 로드 시 또는 상태 변화 시
콘텐츠	짧은 메시지	타이틀 + 설명 (리치)
닫기	자동 소멸 (수초 후)	수동 (closable) 또는 항상 표시
용도	저장 완료, 복사 완료	시스템 상태, 경고, 오류
ARIA	role="status" + aria-live	role="alert" / role="status"

핵심 구분:Toast는 사용자 액션에 대한 일시적인 피드백에, Alert는 페이지 내 영속적인 상태 알림에 사용합니다.

Accessibility

ARIA / WCAG

role="alert" error/warning 시 자동 적용
role="status" default/success/info/loading 시
aria-live="assertive" 긴급 알림 (error/warning)
aria-live="polite" 일반 알림 (default/success/info/loading)
컨테이너에 aria-label="Notifications"
닫기 버튼에 aria-label="Close"
호버 시 타이머 자동 일시정지

Toast

Playground

Types

Features

Action & Cancel

Promise

Close Button

Rich Colors

Loading

API

Component Structure

Props

Toaster

toast() Options

Code Recipes

Anatomy

Best Practices

권장

지양

Toast vs Alert

Accessibility

ARIA / WCAG

Related

Alert

Modal

Badge

Spinner