EmptyState

EmptyState (빈 상태)

EmptyState 컴포넌트는 데이터가 없을 때("no data" 상황) 보여 주는 플레이스홀더 컴포넌트예요. 빈 검색 결과, 빈 테이블·목록, 첫 실행 상태, 오류 일러스트레이션에 선택적 CTA(행동 유도)와 함께 사용해요.

출처: 문서

본문

EmptyState는 "데이터 없음" 상황을 위한 플레이스홀더를 표시해요. 빈 검색 결과, 빈 테이블·목록, 첫 실행 상태, 오류 일러스트레이션에 선택적 call to action을 함께 쓸 수 있어요. 가장 간단한 사용법은 icon, title, description prop을 쓰는 것이에요.

import { Button, EmptyState } from '@mantine/core';
import { MagnifyingGlassIcon } from '@phosphor-icons/react';

function Demo() {
  return (
    <EmptyState
      icon={<MagnifyingGlassIcon />}
      title="No results found"
      description="We couldn't find anything matching your search. Try adjusting your filters or searching with different keywords to see more results."
    >
      <EmptyState.Actions>
        <Button variant="default">Reset filters</Button>
      </EmptyState.Actions>
    </EmptyState>
  );
}

복합 컴포넌트 (Compound components)

콘텐츠를 완전히 제어하려면 shorthand props 대신(또는 함께) 복합 컴포넌트를 사용해요. 사용 가능한 컴포넌트는 다음과 같아요.

  • EmptyState.Indicator – 아이콘 또는 일러스트레이션
  • EmptyState.Title – 제목 텍스트
  • EmptyState.Description – 설명 텍스트
  • EmptyState.Actions – 액션 버튼을 감싸는 wrapper
import { Button, EmptyState } from '@mantine/core';
import { MagnifyingGlassIcon } from '@phosphor-icons/react';

function Demo() {
  return (
    <EmptyState>
      <EmptyState.Indicator>
        <MagnifyingGlassIcon />
      </EmptyState.Indicator>
      <EmptyState.Title>No results found</EmptyState.Title>
      <EmptyState.Description>
        We couldn't find anything matching your search. Try adjusting your filters or searching with
        different keywords to see more results.
      </EmptyState.Description>
      <EmptyState.Actions>
        <Button variant="default">Reset filters</Button>
        <Button variant="default">Create new</Button>
      </EmptyState.Actions>
    </EmptyState>
  );
}

Shorthand props와 복합 컴포넌트를 섞어 쓸 수 있어요. 둘 다 제공되면 icon, title, description prop의 콘텐츠가 먼저 렌더링되고, 그 다음 children이 렌더링돼요.

import { Button, EmptyState } from '@mantine/core';

function Demo() {
  return (
    <EmptyState icon={<Icon />} title="No results found">
      {/* Rendered after the title */}
      <EmptyState.Actions>
        <Button variant="default">Reset filters</Button>
      </EmptyState.Actions>
    </EmptyState>
  );
}

정렬 (Alignment)

align prop으로 콘텐츠를 어떻게 배치할지 제어할 수 있어요.

  • center(기본) – indicator, title, description, actions가 중앙 정렬된 세로 컬럼으로 쌓여요
  • left – indicator가 왼쪽에 배치되고, 콘텐츠는 그 오른쪽에 정렬돼요
  • right – indicator가 오른쪽에 배치되고, 콘텐츠는 그 왼쪽에 정렬돼요

left와 right 정렬에서는 indicator가 콘텐츠의 위쪽에 정렬돼요.

Variant

variant prop을 filled나 light로 설정하면 아이콘이 색상이 있는 원형 indicator 안에 표시돼요. color prop으로 indicator 색상을 바꿀 수 있어요. variant가 설정되지 않으면 아이콘이 dimmed 색상으로 표시돼요.

import { EmptyState } from '@mantine/core';
import { MagnifyingGlassIcon } from '@phosphor-icons/react';

function Demo() {
  return (
    <EmptyState
      icon={<MagnifyingGlassIcon />}
      title="No results found"
      description="We couldn't find anything matching your search. Try adjusting your filters or searching with different keywords to see more results." color="blue"
    />
  );
}

Indicator 배경

withIndicatorBackground prop을 설정하면 variant 없이 indicator 뒤에 중립적인 원형 배경을 표시해요.

import { Button, EmptyState } from '@mantine/core';
import { ShoppingCartSimpleIcon } from '@phosphor-icons/react';

function Demo() {
  return (
    <EmptyState withIndicatorBackground icon={<ShoppingCartSimpleIcon />} title="Your cart is empty">
      <EmptyState.Description>
        Your shopping cart is empty right now. Browse our catalog and add the items you like to get
        started with your first order.
      </EmptyState.Description>
      <EmptyState.Actions>
        <Button variant="default">Browse products</Button>
      </EmptyState.Actions>
    </EmptyState>
  );
}

크기 (Size)

EmptyState는 xs, sm, md, lg, xl 크기를 지원해요. size prop은 indicator 크기, 요소 사이의 간격, 제목·설명의 폰트 크기를 제어해요.

제목 heading 레벨

기본적으로 EmptyState.Title은 시맨틱 heading 레벨이 없는 div 요소를 렌더링해요. 제목이 heading이어야 한다면 order prop을 설정해 h1–h6 요소로 렌더링할 수 있어요.

import { EmptyState } from '@mantine/core';

function Demo() {
  return (
    <EmptyState>
      <EmptyState.Title order={2}>No results found</EmptyState.Title>
    </EmptyState>
  );
}

Styles API

EmptyState는 Styles API를 지원해요. classNames prop으로 내부 요소에 스타일을 추가할 수 있어요.

주요 선택자는 다음과 같아요.

  • root – 루트 요소
  • body – title, description, actions를 감싸는 wrapper
  • indicator – 아이콘이나 일러스트레이션을 감싸는 wrapper
  • title – 제목 요소
  • description – 설명 요소
  • actions – 액션 버튼을 감싸는 wrapper

접근성 (Accessibility)

  • 루트 요소는 일반 div이며 랜드마크(landmark) role이 지정되지 않아요.
  • EmptyState.Title은 기본적으로 heading이 아닌 div를 렌더링해요. 제목을 보조 기술(assistive technology)에 heading으로 노출해야 한다면 order prop을 설정해요.
  • 액션 버튼은 전달된 그대로 렌더링돼요. 접근 가능한 라벨이 있는지 확인해요.

더 알아보기 (Learn more)

  • Card — 콘텐츠를 담는 카드 컴포넌트
  • Button — 버튼 컴포넌트
  • Badge — 뱃지 컴포넌트