Empty

내용이 있었어야 할 자리를 대신 채웁니다. 글리프 하나와 제목, 문장 한 줄, 그리고 다음 행동으로 이어지는 버튼으로 이루어집니다. 아무것도 걸리지 않은 검색 결과, 아직 아무도 쓰지 않은 받은 편지함, 첫 파일이 놓이기 전의 폴더에 씁니다.

import { Button, Empty } from 'neba';

<Empty title="No projects yet" action={<Button size="sm">Create a project</Button>}>
  Everything you deploy shows up here.
</Empty>;

Props

Prop	타입	기본값	설명
variant공통	'solid' | 'outline' | 'text'	'text'	표면의 무게. 빈 상태는 대개 Card의 본문이나 Table의 아래처럼 이미 표면이 있는 자리에 놓이므로 기본값이 text입니다
size공통	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	타입 스케일과 글리프 크기, 그리고 상태가 차지하는 세로 여백
color공통	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'secondary'	색 계열. 시트는 물들지 않고 하이라인과 focus ring까지만 닿습니다. secondary에서 옮길 만한 때는 비어 있다는 사실 자체가 문제일 때입니다. 불러오지 못한 영역의 danger처럼
density공통	'default' | 'compact'	'default'	여백만 바꿉니다. 높이와 글자 크기는 그대로
elevation공통	0 | 1 | 2 | 3	0	그림자 깊이. 0이 거의 언제나 맞습니다. 빈 상태는 이미 있는 표면에 뚫린 구멍이지 그 자체로 한 장의 시트가 아닙니다
title	ReactNode | false	locale's wording	제목 줄. 기본값은 locale이 “여기에는 아무것도 없다”를 말하는 방식이고, false면 글리프와 문장만 남습니다
icon	ReactNode | false	—	제목 위의 글리프. 기본값은 빈 트레이, false면 생략. svg는 size 사다리에 맞춰지고 그 밖의 것(일러스트, 브랜드 마크)은 원래 크기 그대로입니다
action	ReactNode	—	본문 아래에 놓이는 다음 할 일, “첫 항목 만들기” 버튼, “필터 지우기” 링크. 여럿이면 한 줄에 놓이고 함께 줄바꿈됩니다
locale	string	'en'	기본 제목의 언어. BCP 47 태그(ko, pt-BR, zh-Hant). title을 주면 무시되고, 모르는 태그는 영어로 돌아갑니다
children	ReactNode	—	제목 아래 한 문장, 왜 비어 있는지, 다음에 무엇을 할지
transition공통	NebaTransition	—	mount 시 한 번 실행되는 등장 애니메이션 (transition="fade"). 트리거나 반복이 필요하면 Animate* 컴포넌트로 감싸세요
render	useRender.RenderProp	—	div 대신 다른 요소로 렌더링합니다 (render={<td colSpan={5} />}). Base UI의 render prop 그대로

<div>의 기본 속성은 그대로 전달되며, render로 요소를 바꿀 수 있습니다. 공통 축은 prop 규칙에서 설명합니다.

예시

title

제목의 기본값은 locale이 "여기에는 아무것도 없다"를 표현하는 문장입니다. 그래서 prop을 하나도 주지 않은 Empty도 문장 하나는 보여 줍니다. 무엇이 없는지 짚어 주는 쪽은 title이고, 대개 그렇게 쓰는 편이 좋습니다. title={false}는 제목 없이 글리프와 문장만 남깁니다.

import { Empty } from 'neba';

export default function EmptyTitle() {
  return (
    <div className="grid w-full gap-4 sm:grid-cols-3">
      <Empty variant="outline" />

      <Empty variant="outline" title="No invoices">
        Nothing has been billed to this account yet.
      </Empty>

      <Empty variant="outline" title={false}>
        Nothing matched that filter.
      </Empty>
    </div>
  );
}

icon

icon은 다른 아이콘 세트의 글리프나 일러스트, 브랜드 마크 등 어떤 노드든 받아 기본 트레이를 대신합니다. <svg>는 size 사다리에 맞춰지고 그 밖의 것은 원래 크기 그대로 놓입니다. icon={false}는 글리프를 없앱니다.

import { Empty } from 'neba';

function SearchIcon() {
  return (
    <svg viewBox="0 0 16 16" fill="none" aria-hidden="true">
      <circle cx="7.25" cy="7.25" r="4.5" stroke="currentColor" strokeWidth="1.5" />
      <path
        d="m10.6 10.6 2.65 2.65"
        stroke="currentColor"
        strokeWidth="1.5"
        strokeLinecap="round"
      />
    </svg>
  );
}

export default function EmptyIcon() {
  return (
    <div className="grid w-full gap-4 sm:grid-cols-3">
      <Empty variant="outline" title="Default" />

      <Empty variant="outline" icon={<SearchIcon />} title="Your own glyph" />

      <Empty variant="outline" icon={false} title="No glyph at all" />
    </div>
  );
}

action

action은 본문 아래에 놓여 다음 행동으로 이어 줍니다. 첫 항목을 만드는 버튼이나 아무것도 걸리지 않은 필터를 지우는 링크가 여기에 들어갑니다. 여럿이면 fragment로 넘기면 되고, 한 줄에 놓여 함께 줄바꿈됩니다.

import { Button, Empty, TextLink } from 'neba';

export default function EmptyAction() {
  return (
    <div className="grid w-full gap-4 sm:grid-cols-2">
      <Empty
        variant="outline"
        title="No results"
        action={
          <Button size="sm" variant="outline">
            Clear filters
          </Button>
        }
      >
        Nothing matched <strong>ingress-nginx</strong>.
      </Empty>

      <Empty
        variant="outline"
        title="No team members"
        action={
          <>
            <Button size="sm">Invite someone</Button>
            <TextLink href="#action">Read about roles</TextLink>
          </>
        }
      >
        You are the only one here so far.
      </Empty>
    </div>
  );
}

variant

기본값은 text이고, 기본이 text인 곳은 여기뿐입니다. 빈 상태는 대개 이미 Card나 Table, 혹은 패널 안에 놓이는데 사각형 안에 사각형을 하나 더 그리는 것은 하나가 더 많은 것이기 때문입니다. outline과 solid는 그 영역의 경계를 표시해 줄 것이 달리 없을 때를 위한 것입니다.

import { Empty } from 'neba';

export default function EmptyVariants() {
  return (
    <div className="grid w-full gap-4 sm:grid-cols-3">
      <Empty variant="text" title="text" />
      <Empty variant="outline" title="outline" />
      <Empty variant="solid" title="solid" />
    </div>
  );
}

size와 density

size는 타입 스케일과 글리프 크기, 그리고 상태가 세로로 차지하는 자리를 정합니다. density는 여백만 바꾸며, 컨트롤 한 줄 높이 안에 상태를 넣어야 할 때 꺼내 쓰는 쪽입니다.

import { Empty } from 'neba';

export default function EmptySize() {
  return (
    <div className="flex w-full flex-col gap-4">
      <Empty variant="outline" size="sm" title="sm" />
      <Empty variant="outline" size="md" title="md" />
      <Empty variant="outline" size="lg" title="lg" />
      <Empty variant="outline" size="lg" density="compact" title="lg, compact" />
    </div>
  );
}

color

시트는 물들지 않습니다. color는 하이라인과 focus ring까지만 닿고 거기서 멈춥니다. 기본값이 secondary인 이유는, 강조색을 입고 등장하는 빈 상태가 존재하지 않는 내용에 대해 무언가를 주장하는 셈이기 때문입니다. 비어 있다는 사실 자체가 문제일 때 옮기세요.

import { Button, Empty } from 'neba';

export default function EmptyColor() {
  return (
    <div className="grid w-full gap-4 sm:grid-cols-2">
      <Empty variant="outline" title="No events">
        Nothing has happened in the last hour.
      </Empty>

      <Empty
        variant="outline"
        color="danger"
        title="Could not load events"
        action={
          <Button size="sm" variant="outline" color="danger">
            Try again
          </Button>
        }
      >
        The request timed out after 30 seconds.
      </Empty>
    </div>
  );
}

locale

locale은 BCP 47 태그이고 기본 제목의 언어만 정합니다. title을 주면 무시되며, 모르는 태그는 영어로 돌아갑니다.

import { Empty } from 'neba';

const LOCALES = ['en', 'ko', 'ja', 'fr', 'ar'];

export default function EmptyLocale() {
  return (
    <div className="grid w-full gap-4 sm:grid-cols-3">
      {LOCALES.map((locale) => (
        <Empty key={locale} variant="outline" size="sm" locale={locale} />
      ))}
    </div>
  );
}

Table 안에서

Table에는 행 대신 무엇을 보여 줄지 정하는 empty prop이 있고, 모든 열을 가로지르는 셀 하나에 렌더링됩니다. 그 셀은 자기 여백을 가지고 있으므로 대개 density="compact"와 함께 쓰는 편이 맞습니다.

import { Button, Empty, Table, type TableColumn } from 'neba';

interface Deploy {
  id: string;
  environment: string;
  status: string;
}

const HEADERS: TableColumn<Deploy>[] = [
  { key: 'environment', label: 'Environment', width: 200 },
  { key: 'status', label: 'Status' }
];

export default function EmptyTable() {
  return (
    <Table
      headers={HEADERS}
      items={[]}
      getRowKey={(row) => row.id}
      empty={
        <Empty
          density="compact"
          title="No deploys yet"
          action={<Button size="sm">Deploy the main branch</Button>}
        >
          Every deploy and its outcome will be listed here.
        </Empty>
      }
    />
  );
}

접근성

• root는 role="status" live region입니다. 읽는 사람 눈앞에서 목록이 비면 조용히 백지가 되는 대신 그 사실을 알립니다. 처음부터 페이지의 일부로 놓이는 상태라면 role={undefined}을 넘기세요.
• 기본 글리프는 aria-hidden입니다. 제목이 이미 말한 것 외에 무엇도 새로 말하지 않기 때문입니다.
• 내용이 아직 오는 중이라면 Skeleton을, 올 것이 없다는 사실이 확인된 뒤에야 Empty를 쓰세요. 둘 다 보여 주지 않으면 답이 있어야 할 자리에 빈 사각형이 남습니다.