Toast
흐름을 막지 않으면서 짧은 결과와 다음 액션을 겹겹이 알려주는 컴포넌트예요.
Toast는 저장 완료, 업로드 실패, 되돌리기처럼 지금 화면을 떠나지 않고도 바로 알아야 하는 짧은 결과를 보여줄 때 사용해요. 사용자가 반드시 멈춰서 읽거나 선택해야 하는 흐름이라면 Toast보다 Dialog나 AlertDialog를 사용해요.
Anatomy
Toast는 Toaster가 화면 가장자리에 stack을 만들고, 각 항목은 Toast.Root, Toast.Icon, Toast.Content, Toast.Title, Toast.Description, Toast.Action으로 조합해요.
기본 구성
기본 사용에서는 앱 루트 가까이에 Toaster를 1번만 마운트하고, 필요한 곳에서 toast("링크를 복사했어요.")처럼 호출해요. 설명은 선택 사항이라 필요한 맥락이 있을 때만 description으로 덧붙여요. 같은 흐름 안에서 여러 알림이 연달아 생기면 최신 Toast가 앞에 남고, hover 중에는 자동으로 닫히지 않아요.
Properties
Variant
Toast는 default, success, error, warning, info variant를 가져요. 일반 결과에는 default를, 성공과 실패처럼 의미가 분명한 알림에는 각 variant를 그대로 사용해요. 의미 variant는 텍스트 색을 강하게 바꾸기보다 아이콘으로 상태를 먼저 구분해요.
Default
default는 링크 복사, 프로젝트 보관처럼 성공과 실패를 강하게 구분하지 않아도 되는 짧은 결과에 사용해요.
Default
Success
success는 저장, 전송, 동기화처럼 사용자가 기대한 작업이 잘 끝났을 때 사용해요.
Success
Warning
warning은 지금 계속 진행할 수 있지만 사용자가 확인하면 좋은 상태에 사용해요.
Warning
Error
error는 실패한 작업이나 바로 확인해야 하는 문제를 짧게 알려줄 때 사용해요.
Error
Info
info는 다음에 참고하면 좋은 일반 정보나 새 기능 안내처럼 가벼운 맥락에 사용해요.
Info
Action
Toast는 action 1개만 둘 수 있어요. 사용자가 지금 바로 해야 하는 가장 중요한 다음 행동만 남기고, 분기가 여러 개 필요하면 Toast 대신 다른 패턴으로 옮겨요.
Action
State
Toast는 보이는 상태와 닫히는 상태를 가져요. 닫히는 동안에는 다음 Toast가 자연스럽게 앞으로 이동하고, hover나 focus가 있는 동안에는 자동 닫힘이 잠시 멈춰요.
Stack
Guidelines
짧은 결과를 빠르게 알리기
저장 완료, 동기화 실패, 링크 복사처럼 짧게 확인하고 바로 지나갈 수 있는 결과에 사용해요. 사용자가 반드시 읽고 결정을 내려야 하거나 내용이 복잡하다면 Toast 대신 더 명확한 확인 패턴을 사용해요.
제목에 결과를 먼저 쓰기
제목은 무슨 일이 일어났는지 먼저 보여줘요. 설명은 필수가 아니며, 왜 그런지 또는 지금 무엇을 할 수 있는지처럼 다음 행동을 돕는 맥락이 있을 때만 짧게 덧붙이면 충분해요. 제목만으로 이해할 수 있다면 description을 생략해도 좋아요.
액션은 1개만 두기
되돌리기, 다시 시도처럼 바로 할 수 있는 행동이 있다면 action 하나만 남기는 편이 읽기 쉬워요. 선택지가 여러 개로 늘어나면 Toast보다 더 분명한 패턴이 잘 맞아요.
화면을 가리지 않게 유지하기
Toast는 현재 흐름을 막지 않는다는 점이 중요해요. 너무 많은 문장이나 폼 요소를 넣기보다, 지금 당장 알아야 하는 정보와 짧은 액션만 남겨요.
다음에 읽으면 좋은 문서
- 결과를 막아 세워야 하는 흐름은 Dialog와 AlertDialog에서 비교해요.
- 제목과 설명 문구는 Writing 기준을 따라요.
- 상태별 강조와 의미 구분은 Color에서 확인해요.
Schema
Public Anatomy
컴포넌트가 어떤 구성 요소로 이루어지는지 보여줘요. 스타일 타깃으로 표시된 항목만 definition과 recipe에서 직접 스타일링해요.
| 이름 | 필수 | 스타일 타깃 | 설명 |
|---|---|---|---|
region | 필수 | 예 | 여러 Toast를 화면 가장자리에서 묶어 보여주는 라이브 영역이에요. |
root | 필수 | 예 | 한 개의 Toast surface와 stack motion을 소유하는 루트예요. |
content | 필수 | 예 | 제목과 설명을 세로로 정리하는 내부 레이아웃이에요. |
icon | 선택 | 예 | Toast의 의미를 보조하는 선택 아이콘이에요. |
title | 필수 | 예 | 결과를 먼저 읽는 짧은 제목이에요. |
description | 선택 | 예 | 상황을 이해하는 데 필요한 보조 설명이에요. |
action | 선택 | 예 | 가장 중요한 후속 작업을 바로 실행하는 액션이에요. |
Internal Anatomy
| 이름 | 스타일 타깃 | 설명 |
|---|---|---|
viewport | 예 | stack의 hover 경계와 겹침 레이아웃을 소유하는 내부 프레임이에요. |
Variants
| 이름 | 기본값 | 옵션 |
|---|---|---|
| 유형 | default | default일반적인 진행 결과를 중립적으로 알려줘요.success작업이 잘 끝났음을 알려줘요.error즉시 확인이 필요한 실패나 위험을 알려줘요.warning지금은 계속 진행할 수 있지만 확인이 필요한 상황을 알려줘요.info다음에 참고하면 좋은 일반 정보를 알려줘요. |
States
사용자가 느끼거나 컴포넌트가 실제로 드러내는 상태를 설명해요. 각 항목에는 recipe와 runtime이 함께 읽는 바인딩 정보를 적어요.
| 이름 | 바인딩 | 설명 |
|---|---|---|
open | [data-state="open"] | Toast가 보이고 읽을 수 있어요. |
closed | [data-state="closed"] | Toast가 닫히는 중이거나 제거를 기다리고 있어요. |
focusVisible | :focus-visible[data-focus-visible] | 키보드 포커스로 액션의 focus ring이 보여요. |
Styling Hooks
사용자에게 보이는 상태라기보다 스타일을 나눌 때 쓰는 조건에 가까워요. 각 항목에는 상태와 마찬가지로 recipe와 runtime이 함께 읽는 바인딩 정보를 적어요.
| 이름 | 바인딩 | 설명 |
|---|---|---|
entering | [data-entering] | 새 Toast가 stack 앞쪽으로 들어오는 동안만 enter motion을 적용해요. |
Accessibility
| 역할 | status |
|---|---|
| 키보드 |
|
| 요구사항 |
|