EmptyState
먼저 보고, 그다음 계약을 읽습니다
"데이터/결과 없음" 상태의 표준 placeholder — icon·title·description·action 4파트.
Component intent의도와 경계 읽기
list/table/result 화면이 "아직 없음" 또는 "찾을 수 없음"을 친절히 안내하는 그릇. 중앙 정렬 컬럼에 dashed 테두리, 배경은 transparent 라 Card 안/밖 어디에 넣어도 자연스럽다. size 가 padding·아이콘 박스·폰트 비례를, tone 이 아이콘/테두리 tint(semantic)를 결정한다. action/secondaryAction 으로 "다음 행동"을 한 클릭으로 유도한다.
예제
SSOT에 등록된 실제 API 기준 snippet입니다. standalone 배지만 독립 실행 단위이며, fragment는 주변 state·handler 문맥을 생략합니다.
import { EmptyState, Button } from "@axe/ui";<EmptyState icon="📭" title="아직 딜이 없습니다" description="첫 번째 딜을 소싱하면 여기에 표시됩니다." action={<Button variant="primary">딜 추가</Button>}/>import { EmptyState } from "@axe/ui";<EmptyState size="sm" title="검색 결과가 없습니다" description="다른 키워드로 다시 시도해 보세요." announce/><div class="axe-empty-state axe-empty-state--size-lg axe-empty-state--tone-warning"> <div class="axe-empty-state__icon" aria-hidden>⚠</div> <div class="axe-empty-state__title">권한이 없습니다</div> <div class="axe-empty-state__description">관리자에게 접근을 요청하세요.</div> <div class="axe-empty-state__actions"> <button class="axe-btn axe-btn--secondary">요청 보내기</button> </div></div>Props
TSX 소스가 진실입니다. 주요 export 컴포넌트의 public API만 노출합니다.
| 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
title | string | 필수 | — | 한 줄 제목(`.axe-empty-state__title`). ReactNode 가 아닌 문자열. |
icon | React.ReactNode | — | — | 중앙 상단 아이콘(emoji/svg/컴포넌트). 미지정 시 아이콘 슬롯 자체가 렌더되지 않는다. |
description | React.ReactNode | — | — | 보조 설명(`.axe-empty-state__description`, max 48ch). |
action | React.ReactNode | — | — | 1차 행동 — 보통 <Button variant="primary">. |
secondaryAction | React.ReactNode | — | — | 2차 행동 — link 또는 ghost 버튼. action 옆에 나란히 렌더. |
size | "sm" | "md" | "lg" | — | "md" | padding·아이콘 박스·폰트 크기 비례. |
tone | "default" | "success" | "warning" | "danger" | — | "default" | 아이콘 tint + subtle 테두리 accent. default 는 추가 클래스 없이 text-muted. |
announce | boolean | — | false | true 면 role="status" + aria-live="polite" 를 부여해 SR 에 자동 발화. 비동기로 빈 결과가 생길 때(예: 검색 0건)만 켠다. |
...rest | Omit<React.HTMLAttributes<HTMLDivElement>, "title"> | — | — | className 병합, 나머지는 루트 div 로 전파. |
.axe-* 클래스 계약
React 밖에서도 같은 표면을 그리는 공개 계약입니다. stable은 minor 버전 안에서 이름을 바꾸지 않습니다.
| 클래스 | 안정성 | 용도 |
|---|---|---|
.axe-empty-state | stable | 루트 div — 중앙 정렬 컬럼·dashed 테두리·transparent 배경. |
.axe-empty-state__icon | stable | 원형 아이콘 박스(subtle 배경, 크기는 size 에 비례). |
.axe-empty-state__title | stable | 제목 — display 폰트. |
.axe-empty-state__description | stable | 설명 문단(secondary·max 48ch). |
.axe-empty-state__actions | stable | action + secondaryAction row(flex wrap, 중앙). |
.axe-empty-state--size-sm | stable | 작은 크기 — padding·아이콘 36px·폰트 축소. |
.axe-empty-state--size-lg | stable | 큰 크기 — padding·아이콘 64px·폰트 확대(md 는 기본, 클래스 없음). |
.axe-empty-state--tone-success | stable | success tone — 아이콘 success-soft/success + 테두리 accent. |
.axe-empty-state--tone-warning | stable | warning tone — 아이콘 warning tint + 테두리 accent. |
.axe-empty-state--tone-danger | stable | danger tone — 아이콘 danger tint + 테두리 accent(default 는 클래스 없음). |
접근성
키보드, ARIA, 구현 노트를 함께 검토합니다.
기본은 시맨틱 중립 placeholder(정적 mount 마다 읽히는 noise 회피). announce=true 일 때만 role="status" + aria-live="polite" 로 SR 통지. 아이콘은 `aria-hidden`.
title 은 heading 이 아니라 div — 화면 맥락상 제목이 필요하면 상위에서 heading 을 제공한다. announce 는 비동기 빈 결과 통지에만(정적 placeholder 에 켜면 매 mount 발화되는 noise).