Alert
페이지 내 정적 배너 — variant 4종. 뉴트럴 표면 + 채운 아이콘 배지로 의미를 전하고, error만 role="alert"로 즉시 낭독됩니다.
마지막 업데이트 2026-06-28
한눈에#
Toast가 “지나가는 알림”이라면 Alert는 페이지에 머무는 배너입니다 — 폼 상단 오류 요약, 페이지 공지처럼 콘텐츠와 함께 읽혀야 할 때 씁니다.
저장 완료
토큰 만료 임박
저장 실패
- 의미 4종
- 채운 아이콘 배지
- hairline + 떠오름
- error만 role=alert
채운 아이콘 배지로 의미를 구분하고, 색맹 안전을 위해 아이콘 모양과 제목 텍스트가 병행합니다
사용 시점#
폼·페이지에 머물러 읽혀야 할 배너면 Alert — 그 외에는 목적에 맞는 컴포넌트를 가리킵니다.
권장 — 이렇게 쓰세요
지양 — 이러지 마세요
저장 실패
쓴다 — 폼 상단 오류 요약·페이지 공지처럼 콘텐츠와 함께 페이지에 머무는 배너
대신 Toast — 작업 결과를 잠깐 띄웠다 자동으로 사라지게(흐름 비차단)
대신 Modal — 사용자의 확인/차단을 강제해야 할 때
대신 FormMessage — 폼 안 제출 실패·검증 메시지(CTA 위 Tier 2 — Alert는 상단 요약 Tier 3)
화면 단위 판단은 Loading Feedback을 따릅니다. Alert는 페이지에 머물러야 하는 공지·오류 요약용이며, 폼 제출 실패는 FormMessage로 더 좁게 둡니다.
플레이그라운드#
컨트롤로 props를 조작하면 미리보기와 코드가 실시간 갱신됩니다.
Alert를 직접 조작해 보세요
속성·테마·토큰을 바꾸고 React·Flutter 코드를 확인하는 풀스크린 빌더로 엽니다.
플레이그라운드는 넓은 작업 영역이 필요해 웹·태블릿에서 편집할 수 있어요.
변형#
안내
저장 완료
토큰 만료 임박
저장 실패
의미색은 채운 아이콘 배지가 전담합니다 — 배지 채움은 *-text(깊은 잉크),
글리프는 surface입니다. 두 색은 테마마다 명도 양 끝에 있어 라이트·다크 모두 AA
4.5:1을 넘기고, 그 대비는 빌드 게이트가 강제합니다. (warning은 amber.500을 채우면
흰 글리프가 1.7:1로 미달이라, 더 진한 warning-text를 배지 채움색으로 씁니다.)
외형#
appearance로 두 외형을 고릅니다 — 기본 standard(뉴트럴 표면 + 떠오름 + solid 배지)와
tonal(의미색 8% 틴트 + 평면 + soft 배지 + 액센트 제목). 폼·리스트에 차분히 섞일 땐
standard, 페이지 상단 공지처럼 의미를 강하게 드러낼 땐 tonal을 권합니다.
저장 완료
저장 완료
저장 실패
tonal은 8% 틴트 위 *-text 제목이라 AA 4.5:1을 유지합니다(12%는 미달 — 기존
사용처 가드 실측). 배지는 standard가 solid(진한 채움 + 흰 글리프), tonal이
soft(연한 틴트 원 + 액센트 글리프) 로 갈립니다 — 글리프는 비텍스트라 두 외형
모두 대비를 확보합니다.
토큰 만료 임박
7일 안에 API 토큰을 갱신하세요.
onDismiss를 주면 후행에 닫기 IconButton이 렌더됩니다. 가시성은 소비자가
소유합니다 — 클릭 시 onDismiss만 호출되고 실제 제거는 소비자가 합니다.
액션#
actions에 액션을 주면 본문 아래 액션 행이 렌더됩니다 — Material 3 banner처럼
변형 액센트색 텍스트 링크가 기본형입니다. 액션 색은 Alert이 변형 액센트(*-text)를
.actions에 상속 제공하므로, 링크는 color: inherit만으로 올바른 색을 받습니다(인라인
스타일 0). 닫기(onDismiss)와 병행 가능하고, ghost 버튼 등 다른 액션 위젯도 슬롯에
그대로 넣을 수 있습니다.
주의가 필요합니다
카드가 만료되었습니다
소스를 추가했습니다
새 리뷰 37건
크기#
size prop이 없습니다 — 부모 폭을 채우는 유동 배너입니다. children을
생략하면 제목 한 줄짜리 컴팩트 배너가 됩니다. 배지는 본문·액션 유무와 무관하게
항상 제목 첫 줄 중심에 정렬됩니다(음의 마진으로 줄 위로 끌어올림).
상태#
기본은 정적 배너라 인터랙션 상태가 없습니다. onDismiss를 주면 후행 닫기
버튼이 렌더되어 닫을 수 있는 배너가 됩니다 — 단, 가시성은 소비자가 소유합니다
(클릭 시 onDismiss만 호출되고, 실제 제거는 소비자가 Alert를 언마운트). Toast/Modal이
제어를 소비자에게 넘기는 방식과 동일합니다. 닫기 버튼 접근성 이름은 기본 닫기이며
dismissLabel로 재정의합니다. 지나가며 자동 해제되는 알림은
Toast를 쓰세요.
Props#
| Prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
title | ReactNode | — | 배너 제목 |
variant | 'info' | 'success' | 'warning' | 'error' | info | 의미 색 — error만 role="alert" 부여 |
appearance | 'standard' | 'tonal' | standard | 외형 — 기본 'standard'. 강한 의미 강조가 필요하면 'tonal' |
actions | ReactNode | — | 본문 아래 액션 슬롯 — 텍스트/ghost 버튼 권장(Material 3 banner). 미제공 시 영역 미렌더 |
onDismiss | () => void | — | 제공 시 후행 닫기 버튼 렌더 — 클릭하면 호출. 가시성은 소비자가 제어(비표시는 소비자가 언마운트) |
dismissLabel | string | 닫기 | 닫기 버튼 접근성 이름 — 기본 '닫기' |
ref | Ref<HTMLDivElement> | — | 루트 <div>로 전달되는 ref (React 19 ref-as-prop) |
접근성#
- error만
role="alert"— 마운트 시 즉시 낭독됩니다. 나머지 변형은 정적 콘텐츠라 role 없이 문서 흐름대로 읽힙니다 - 아이콘은 장식(
aria-hidden) — 의미는 색 + 제목 텍스트가 병행 전달합니다(색맹 안전) - 잉크는
*-text토큰 — 라이트/다크 모두 AA 대비가 빌드 게이트로 보장됩니다 - 닫기 버튼은 아이콘 전용이라 접근성 이름이 필수입니다 — 기본
닫기,dismissLabel로 재정의(예: ‘공지 닫기’) - Alert 자체는 상태·이펙트가 없습니다 —
onDismiss는 콜백만 받아 가시성 제어를 소비자에게 위임하므로 컴포넌트 RSC 호환성을 유지합니다
토큰#
component 토큰 없이 semantic을 직접 소비합니다(신설 기준 §4 미충족).
| 속성 | 토큰 |
|---|---|
| 표면 | color.surface (뉴트럴) |
| 보더 | color.border (1px hairline) |
| 떠오름 | shadow.sm |
| 아이콘 배지 (standard) | color.*-text solid 채움 + color.surface 글리프 (테마 반전으로 AA 보장) |
| 제목 | color.text + font-size.body-2 + font-weight.semibold (standard) |
| 본문 | color.text-muted + font-size.body-2 |
| 액션 | space.3 gap · space.3 상단 마진 · 색 color.*-text(변형 액센트 상속) |
| 형태 | radius.lg · space.4 · icon.size-md · 배지 36px(icon.size-md + space.2×2) |
외형 tonal | 표면 color.{의미} 8% 틴트 · 보더 30% 틴트 · 제목/배지 글리프 color.*-text · soft 배지 color.{의미} 24% 틴트 · 그림자 없음 |