Sonner 사용하기
초기 응답
이 스킬이 특정 질문 없이 처음 호출되면, 다음 내용으로만 응답하세요:
Sonner 설정, 스타일링 및 문제 해결을 도와드릴 준비가 되었습니다. 제 지식은 Sonner의 창작자 Emil Kowalski의 자료를 바탕으로 합니다.
사용자가 질문을 하기 전까지는 다른 정보를 제공하지 마세요.
Sonner(토스트 라이브러리)에 대한 가이드 스킬입니다. 작업에 Sonner가 관련된 경우(연결, 토스트 렌더링, 스타일링 또는 문제 해결) 이 파일의 내용을 먼저 참고하여 답변하세요. 전체 <Toaster /> 및 toast() prop 테이블은 API.md에 있습니다. 정확한 prop 이름, 타입 또는 기본값이 필요할 때 이 파일을 읽으세요.
설정
두 가지 요소만 있으면 됩니다:
- 하나의
<Toaster />를 한 번만 마운트하고, 가능한 루트에 가깝게 배치하세요(Next.js:layout.tsx— 서버 컴포넌트 내에서도 작동합니다). 페이지별로 또는 조건부로 렌더링하지 마세요. 두 번째 Toaster가 마운트되면 모든 토스트가 중복됩니다. - 클라이언트 코드에서
toast()호출 — 이벤트 핸들러, effects, 콜백에서 사용합니다. 일반 함수이며, 훅이나 프로바이더가 필요하지 않지만 서버에서는 아무 작업도 하지 않습니다. 서버 액션에서는 결과를 반환하고, 이를 받는 클라이언트 코드에서toast()를 호출하세요.
import { Toaster } from 'sonner'; // layout에서 한 번
import { toast } from 'sonner'; // 클라이언트 측 어디서든
올바른 호출 선택하기
| 원하는 기능 | 호출 방법 |
|---|---|
| 일반 메시지 | toast('Title') — 두 번째 줄을 위해 { description } 추가 |
| 성공 / 오류 / 정보 / 경고 아이콘 | toast.success('…'), toast.error('…') 등 |
| 상태를 직접 관리하면서 스피너 표시 | toast.loading('…'), 그런 다음 id로 업데이트 |
| 프로미스에 연결된 로딩 → 성공/오류 | toast.promise(promise, { loading, success, error }) — success/error는 확인된 값/오류를 받는 함수 허용 |
| 작업을 수행하는 버튼 | { action: { label, onClick } } — onClick이 event.preventDefault()를 호출하지 않으면 토스트를 닫습니다. cancel은 보조 변형입니다. |
| 기본 토스트 셸을 가진 사용자 JSX | toast(<jsx />) |
| 스타일이 전혀 없는 사용자 JSX | toast.custom((t) => <jsx />) — headless, t는 닫을 id를 제공 |
레시피
토스트 업데이트 — 동일한 id로 toast()를 다시 호출하면 전달한 prop만 변경됩니다. toast.success(…, { id })로 전환하면 타입이 변경됩니다. toast.promise 없이 로딩 → 성공 흐름을 구현하는 방법입니다:
const id = toast.loading('업로드 중…');
toast.success('업로드 완료', { id });
유지 — { duration: Infinity }. 닫기 — toast.dismiss(id), 또는 전체 닫기는 toast.dismiss(). 활성 토스트 읽기 — React에서는 useSonner(), React 외부에서는 toast.getActiveToasts().
텍스트 내 링크 또는 컴포넌트 — title 또는 description에 함수 전달: toast(() => <a href="…">보기</a>).
다중 Toaster — 각 Toaster에 id를 지정하고 toast('…', { toasterId: 'canvas' })로 대상 지정. toasterId가 없으면 모든 Toaster가 토스트를 렌더링합니다.
닫기 콜백 — onDismiss는 닫기 버튼 또는 스와이프 시 실행됨. onAutoClose는 타임아웃 시 실행됨. 두 개는 별개이며, 단일 "닫힘" 콜백은 없습니다.
스타일링 — 우선 순위 사다리
변경에 필요한 만큼만 올라가되, 너무 일찍 최상단으로 뛰어오르는 것은 괜찮습니다(권장되는 최종 상태임). 중간 단계에 머무르는 것은 좋지 않습니다.
- 기본값 — Toaster에
richColors를 추가하여 화려한 성공/오류 색상 사용,invert로 테마 반전. - 인라인 조정 — Toaster의
toastOptions={{ style: {…} }}로 모든 토스트에 적용, 또는 각toast()호출에style사용. - 부분에 클래스 적용 —
toastOptions={{ classNames: { toast, title, description, actionButton, cancelButton, closeButton } }}. Sonner의 주입된 스타일이 계단식 우선순위를 가지므로 모든 클래스에!important가 필요합니다(Tailwind:!text-red-900). 여러 항목에 important를 표시하고 있다면 중단하고 headless로 가세요. - Headless —
toast.custom()으로 자체 JSX를 사용하고, Sonner의 위치 지정, 쌓기, 스와이프 기능을 유지합니다. 디자인 시스템 토스트에 권장되는 방법: 자체toast()추상화로 래핑하세요. (unstyled: true가 중간 단계로 존재하지만, headless가 동일한 노력으로 더 많은 제어를 제공합니다.)
아이콘 — Toaster의 icons prop으로 유형별 기본 아이콘 교체, 각 토스트에는 icon 사용, null로 제거.
테마 — theme 기본값은 'light'이며 OS를 추적하지 않습니다. theme="system"을 전달하거나 테마 프로바이더 연결: next-themes를 사용하여 <Toaster theme={resolvedTheme} />.
문제 해결
| 증상 | 원인 → 해결 방법 |
|---|---|
| 토스트가 나타나지 않음 | <Toaster />가 마운트되지 않았거나, 마운트가 해제됨(조건부 렌더링, 페이지별 배치). 루트에 하나를 마운트하세요. 서버 액션에서 호출하는 경우: toast()는 클라이언트 전용입니다 — 클라이언트에서 액션 결과와 함께 호출하세요. |
| 동일한 토스트가 두 번 나타남 | 두 개의 Toaster가 마운트됨(layout 및 page) — 하나만 유지하세요. 또는 React StrictMode의 개발 시 이중 호출로 인해 effect에서 toast()가 실행됨 — 이벤트 핸들러에서 호출하거나, 안정적인 id를 전달하여 두 번째 호출이 중복이 아닌 업데이트되도록 하세요. |
| Tailwind/CSS 클래스가 적용되지 않음 | 기본 스타일이 이를 재정의합니다. !important를 표시하거나 unstyled/headless를 사용하세요(위 사다리 참조). |
| 토스트가 완전히 스타일이 없는 상태로 렌더링됨(Astro, view transition에서 자주 발생) | Sonner의 주입된 스타일시트가 손실됨 — layout에서 명시적으로 가져오기: import 'sonner/dist/styles.css'. |
| Shadow DOM 내에서 스타일 없음 | 스타일이 document.head에 배치되며 shadow root에는 배치되지 않음. [data-sonner-toaster]가 포함된 스타일 태그를 shadow root에 복사하세요. |
| 토스트가 모달/오버레이 뒤에 있거나 잘림 | 조상 요소가 쌓임 컨텍스트(transform, filter, overflow)를 만들거나 오버레이가 toaster보다 z-index가 높음. <Toaster />를 문서 루트로 이동하여 대화상자/포털 컨테이너 외부에 배치하세요. |
| 다크 모드 무시 | theme 기본값은 'light' — theme="system"을 설정하거나 확인된 테마를 전달하세요(위 테마 참조). |
| 성공/오류가 녹색/빨간색이 아닌 회색으로 표시됨 | 기본값입니다. Toaster에 richColors를 추가하세요. |
| 토스트가 닫히지 않음 | duration: Infinity, dismissible: false, 또는 프로미스가 해결되지 않는 toast.promise — 로딩 토스트가 영원히 기다림. |
toast.promise가 로딩에 멈춤 | 첫 번째 인수로 프로미스(또는 프로미스를 반환하는 함수)가 필요하며, 프로미스가 실제로 resolve/reject되어야 함. |
| 스와이프로 닫기가 잘못된 방향으로 가거나 작동하지 않음 | 방향은 position에서 파생됩니다. Toaster의 swipeDirections로 재정의하세요. |
| 모든 Toaster에 토스트가 표시됨 | 다중 Toaster는 대상 지정이 필요합니다. 각 Toaster에 id를 지정하고 toast() 호출에 toasterId를 전달하세요. |
| 모바일에서 토스트가 화면 가장자리와 너무 가까움 | offset(데스크톱, 기본 32px) 및 mobileOffset(<600px, 기본 16px) — 숫자, CSS 문자열 또는 측면별 객체를 사용합니다. |