Sonner

화면 모서리에 표시되는 토스트 알림 컴포넌트

개요

Sonner 컴포넌트는 sonner  라이브러리를 기반으로 한 토스트 알림 시스템입니다. Toaster를 앱 루트에 한 번 배치하고, toast() 함수를 호출해 알림을 표시합니다. 성공/정보/경고/에러/로딩 타입별 아이콘이 기본 매핑되어 있고, next-themes와 연동되어 테마를 자동으로 따라갑니다.

주요 특징

• ✅ 5가지 타입: success, info, warning, error, loading 아이콘 기본 제공
• ✅ richColors: 타입별 강조 색상 기본 적용
• ✅ 테마 연동: next-themes 기반 라이트/다크 모드 자동 대응
• ✅ 위치 지정: 9개 position 옵션 (top-left ~ bottom-right)
• ✅ 액션 버튼: 실행 취소 등 액션 버튼 포함 가능
• ✅ 디자인 토큰: 테마 커스터마이징 지원

토스트 타입

toast() 함수의 타입별 메서드로 다양한 알림을 표시합니다. 아래는 각 타입의 스타일 미리보기입니다.

import { toast } from "sonner"
 
toast.success("성공적으로 저장되었습니다.")
toast.info("새로운 업데이트가 있습니다.")
toast.warning("저장되지 않은 변경사항이 있습니다.")
toast.error("삭제에 실패했습니다.")
toast.loading("업로드 중...")

설명과 액션

description으로 부가 설명을, action으로 실행 버튼을 추가할 수 있습니다.

// 설명 추가
toast.success("이벤트가 생성되었습니다", {
  description: "2023년 12월 3일 일요일 오전 9:00",
})
 
// 액션 버튼 추가
toast("이벤트가 삭제되었습니다", {
  action: {
    label: "실행 취소",
    onClick: () => console.log("Undo"),
  },
})

API Reference

Toaster Props

sonner의 ToasterProps를 그대로 지원합니다. 주요 props는 다음과 같습니다.

타입별 아이콘(success/info/warning/error/loading)과 toastOptions.classNames는 기본 설정되어 있으며, props로 덮어쓸 수 있습니다.

기본 사용법

// 앱 루트에 Toaster 배치 (1회)
import { Toaster } from "@vortex/ui-foundation"
 
export default function RootLayout({ children }) {
  return (
    <>
      {children}
      <Toaster position="top-right" />
    </>
  )
}
 
// 컴포넌트에서 toast 호출
import { toast } from "sonner"
 
<Button onClick={() => toast("저장되었습니다.")}>저장</Button>

접근성

스크린 리더

• 토스트가 aria-live 영역에 렌더링되어 스크린 리더에 자동으로 알림
• 타입별 아이콘은 장식 요소이며 메시지 텍스트가 핵심 정보를 전달

권장 사항

• ✅ Toaster는 앱 루트에 한 번만 배치
• ✅ 중요한 작업 실패에는 toast.error와 복구 액션 버튼 함께 제공
• ❌ 짧은 시간에 다수의 토스트를 연속 호출하지 않기

관련 컴포넌트

• Spinner: 로딩 상태 인라인 표시
• OverlayLoading: 전체 화면 로딩 오버레이
• Modal: 사용자 확인이 필요한 중요 알림