Badge

다른 요소의 모서리에 겹쳐 놓는 작은 표식입니다. 읽지 않은 개수나 현재 상태를 원래 요소를 가리지 않고 알릴 때 씁니다.

import { Badge, Button } from 'neba';

<Badge content={4} label="읽지 않은 알림 4개">
  <Button startIcon={<BellIcon />} />
</Badge>

<Badge dot color="success" overlap="circle">
  <Avatar />
</Badge>;

Props

Prop	타입	기본값	설명
variant공통	'solid' | 'outline' | 'text'	'solid'	표면의 무게. 채움 / 하이라인 / 없음
size공통	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	표식의 크기. 컨트롤 사다리와 별개입니다. 배지는 무언가의 모서리에 걸리는 것이라 줄을 맞출 상대가 없습니다
color공통	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	의미론적 색 역할. 임의 색상값은 받지 않습니다
density공통	'default' | 'compact'	'default'	숫자 좌우의 여백만 바꿉니다
elevation공통	0 | 1 | 2 | 3	0	그림자 깊이. 0은 그림자 없음
content	ReactNode	—	표식이 말하는 것. 보통 숫자, 가끔 단어. 없으면 점이 됩니다
max	number	99	숫자 content의 상한. 넘으면 99+가 됩니다. 단어는 자르지 않습니다
dot	boolean	false	content가 있어도 점으로 그립니다. 숫자는 스크린 리더에만 남습니다
showZero	boolean	false	0도 보여 줍니다. 기본이 꺼짐인 이유는 읽지 않은 메시지 0개는 소식이 아니기 때문입니다
invisible	boolean	false	자리는 지킨 채 숨깁니다. 다시 나타나도 주변이 움직이지 않습니다
placement공통	'top-start' | 'top-end' | 'bottom-start' | 'bottom-end'	'top-end'	어느 모서리에 붙을지. start/end라서 쓰기 방향을 따라 뒤집힙니다
overlap	'square' | 'circle'	'square'	아래에 있는 것의 모양. 원의 모서리는 사각형보다 중심에서 멀기 때문에 파고드는 깊이가 다릅니다
label	string	—	스크린 리더가 숫자 대신 읽을 문장. 종 옆의 "3"은 아무 뜻도 없습니다
children	ReactNode	—	표식이 붙을 대상. 없으면 인라인으로 놓이는 독립 표식이 됩니다

children을 주면 그것을 감싸는 <span>이 positioning context가 되고 표식은 그 모서리에 붙습니다. children 없이 쓰면 표식 자체가 inline 요소로 놓이므로, 표 안의 상태 표시처럼 단독으로도 쓸 수 있습니다.

공통 축(variant size color density elevation)의 의미는 Prop 규약에 있습니다.

예시

variant와 color

solid는 채운 표식, outline은 테두리와 옅은 panel, text는 배경만 얇게 깔린 형태입니다. color는 여섯 가지 역할 색 중 하나를 고릅니다.

import { Badge, Button } from 'neba';

const COLORS = ['primary', 'secondary', 'success', 'warning', 'danger', 'info'] as const;

export default function BadgeVariants() {
  return (
    <div className="flex flex-col gap-4">
      {(['solid', 'outline', 'text'] as const).map((variant) => (
        <div key={variant} className="flex flex-wrap items-center gap-5">
          {COLORS.map((color) => (
            <Badge key={color} variant={variant} color={color} content={8}>
              <Button variant="outline" color="secondary" size="sm">
                {color}
              </Button>
            </Badge>
          ))}
        </div>
      ))}
    </div>
  );
}

content와 max

content가 표식에 들어갈 내용입니다. 숫자가 max(기본 99)를 넘으면 99+로 표시되고, 문자열은 자르지 않습니다.

content가 0이면 기본적으로 그리지 않습니다. showZero로 켤 수 있습니다. 셀 것은 없지만 알릴 것이 있을 때는 dot으로 점만 찍고, invisible은 레이아웃을 유지한 채 표식만 감춥니다.

import { Badge, Button } from 'neba';

export default function BadgeContent() {
  return (
    <div className="flex flex-wrap items-center gap-6">
      <Badge content={7}>
        <Button variant="outline" color="secondary">
          Seven
        </Button>
      </Badge>

      {/* Past `max`, and the badge says so rather than growing. */}
      <Badge content={1204}>
        <Button variant="outline" color="secondary">
          Capped
        </Button>
      </Badge>

      <Badge content={1204} max={999}>
        <Button variant="outline" color="secondary">
          Higher cap
        </Button>
      </Badge>

      {/* A count of nothing is not news, so it does not show up at all. */}
      <Badge content={0}>
        <Button variant="outline" color="secondary">
          Zero
        </Button>
      </Badge>

      <Badge content={0} showZero color="secondary">
        <Button variant="outline" color="secondary">
          Zero, shown
        </Button>
      </Badge>

      {/* Nothing to count, but something to report. */}
      <Badge dot color="danger">
        <Button variant="outline" color="secondary">
          Dot
        </Button>
      </Badge>
    </div>
  );
}

placement와 overlap

placement는 표식이 붙을 모서리입니다. top/bottom과 start/end를 조합한 네 값이며, start/end를 쓰기 때문에 RTL에서는 좌우가 자동으로 뒤집힙니다.

overlap은 감싼 요소의 모양입니다. circle은 원의 모서리가 bounding box보다 안쪽에 있는 만큼 표식을 더 당겨서, 아바타 위에서도 표식이 떠 보이지 않게 합니다.

import { Badge, Button } from 'neba';

const CORNERS = ['top-start', 'top-end', 'bottom-start', 'bottom-end'] as const;

export default function BadgePlacement() {
  return (
    <div className="flex flex-col gap-6">
      <div className="flex flex-wrap items-center gap-6">
        {CORNERS.map((placement) => (
          <Badge key={placement} placement={placement} content={3}>
            <Button variant="outline" color="secondary" size="lg">
              {placement}
            </Button>
          </Badge>
        ))}
      </div>

      {/* A circle's corner is further from its centre than a square's, so the
          badge has to tuck in further or it floats off the edge. */}
      <div className="flex flex-wrap items-center gap-6">
        {(['square', 'circle'] as const).map((overlap) => (
          <div key={overlap} className="flex items-center gap-3">
            <Badge overlap={overlap} content={3} color="danger">
              <span className="flex size-10 items-center justify-center rounded-full bg-(--n-soft-press) text-[0.8125rem] font-semibold text-(--neba-fg)">
                JD
              </span>
            </Badge>
            <span className="text-[0.75rem] text-(--neba-muted-fg)">overlap="{overlap}"</span>
          </div>
        ))}
      </div>
    </div>
  );
}

size

Badge는 컨트롤 높이 단계를 쓰지 않고 자체 단계를 씁니다. md가 18px이며, 두 자리 숫자가 읽히는 가장 작은 크기입니다.

import { Badge, Button } from 'neba';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl'] as const;

export default function BadgeSizes() {
  return (
    <div className="flex flex-col gap-5">
      <div className="flex flex-wrap items-center gap-6">
        {SIZES.map((size) => (
          <Badge key={size} size={size} content={12}>
            <Button size={size} variant="outline" color="secondary">
              {size}
            </Button>
          </Badge>
        ))}
      </div>
      <div className="flex flex-wrap items-center gap-6">
        {SIZES.map((size) => (
          <Badge key={size} size={size} dot color="success">
            <Button size={size} variant="outline" color="secondary">
              {size}
            </Button>
          </Badge>
        ))}
      </div>
    </div>
  );
}

접근성

• content={3}만 있으면 screen reader에는 "3"으로 읽힙니다. label에 문장을 주면 그 문장이 표식의 accessible name이 됩니다.

<Badge content={3} label="읽지 않은 알림 3개">
  <Button startIcon={<BellIcon />} aria-label="알림" />
</Badge>

• dot일 때도 content는 DOM에 남아 시각적으로만 가려지므로, 점이 무엇을 뜻하는지 읽을 수 있습니다.
• invisible이거나 표시할 내용이 없으면 DOM에서도 제거됩니다. 화면에 없는 표식의 글자가 find-on-page에 잡히지 않습니다.