StatusBadge

Compound 패턴 기반 상태 배지 컴포넌트. status × type 조합으로 6가지 시맨틱 상태를 4가지 시각 강도로 표현.

개요

StatusBadge는 Compound Pattern으로 설계된 상태 배지 컴포넌트입니다.

6가지 status — default, informative, primary, success, warning, error
4가지 type — filled, tint, outline, subtle로 강조 수준 조절
반응형 size — { mobile: 'sm', desktop: 'lg' } 형태로 breakpoint별 크기 지정
Compound sub-components — StatusBadge.Dot, StatusBadge.Icon, StatusBadge.Text, StatusBadge.Loader로 유연한 조합

Usage

기본 사용법

status × type 조합으로 배지의 의미와 시각적 강도를 결정합니다.

<VStack $css={{ gap: '$spacing-200', alignItems: 'flex-start' }}>
{/* filled */}
<HStack $css={{ gap: '$spacing-150', flexWrap: 'wrap' }}>
  <StatusBadge.Root status="default" variant="filled"><StatusBadge.Text>Default</StatusBadge.Text></StatusBadge.Root>
  <StatusBadge.Root status="informative" variant="filled"><StatusBadge.Text>Informative</StatusBadge.Text></StatusBadge.Root>
  <StatusBadge.Root status="primary" variant="filled"><StatusBadge.Text>Primary</StatusBadge.Text></StatusBadge.Root>
  <StatusBadge.Root status="success" variant="filled"><StatusBadge.Text>Success</StatusBadge.Text></StatusBadge.Root>
  <StatusBadge.Root status="warning" variant="filled"><StatusBadge.Text>Warning</StatusBadge.Text></StatusBadge.Root>
  <StatusBadge.Root status="error" variant="filled"><StatusBadge.Text>Error</StatusBadge.Text></StatusBadge.Root>
</HStack>

{/* tint */}
<HStack $css={{ gap: '$spacing-150', flexWrap: 'wrap' }}>
  <StatusBadge.Root status="default" variant="tint"><StatusBadge.Text>Default</StatusBadge.Text></StatusBadge.Root>
  <StatusBadge.Root status="informative" variant="tint"><StatusBadge.Text>Informative</StatusBadge.Text></StatusBadge.Root>
  <StatusBadge.Root status="primary" variant="tint"><StatusBadge.Text>Primary</StatusBadge.Text></StatusBadge.Root>
  <StatusBadge.Root status="success" variant="tint"><StatusBadge.Text>Success</StatusBadge.Text></StatusBadge.Root>
  <StatusBadge.Root status="warning" variant="tint"><StatusBadge.Text>Warning</StatusBadge.Text></StatusBadge.Root>
  <StatusBadge.Root status="error" variant="tint"><StatusBadge.Text>Error</StatusBadge.Text></StatusBadge.Root>
</HStack>

{/* outline */}
<HStack $css={{ gap: '$spacing-150', flexWrap: 'wrap' }}>
  <StatusBadge.Root status="default" variant="outline"><StatusBadge.Text>Default</StatusBadge.Text></StatusBadge.Root>
  <StatusBadge.Root status="informative" variant="outline"><StatusBadge.Text>Informative</StatusBadge.Text></StatusBadge.Root>
  <StatusBadge.Root status="primary" variant="outline"><StatusBadge.Text>Primary</StatusBadge.Text></StatusBadge.Root>
  <StatusBadge.Root status="success" variant="outline"><StatusBadge.Text>Success</StatusBadge.Text></StatusBadge.Root>
  <StatusBadge.Root status="warning" variant="outline"><StatusBadge.Text>Warning</StatusBadge.Text></StatusBadge.Root>
  <StatusBadge.Root status="error" variant="outline"><StatusBadge.Text>Error</StatusBadge.Text></StatusBadge.Root>
</HStack>

{/* subtle */}
<HStack $css={{ gap: '$spacing-150', flexWrap: 'wrap' }}>
  <StatusBadge.Root status="default" variant="subtle"><StatusBadge.Text>Default</StatusBadge.Text></StatusBadge.Root>
  <StatusBadge.Root status="informative" variant="subtle"><StatusBadge.Text>Informative</StatusBadge.Text></StatusBadge.Root>
  <StatusBadge.Root status="primary" variant="subtle"><StatusBadge.Text>Primary</StatusBadge.Text></StatusBadge.Root>
  <StatusBadge.Root status="success" variant="subtle"><StatusBadge.Text>Success</StatusBadge.Text></StatusBadge.Root>
  <StatusBadge.Root status="warning" variant="subtle"><StatusBadge.Text>Warning</StatusBadge.Text></StatusBadge.Root>
  <StatusBadge.Root status="error" variant="subtle"><StatusBadge.Text>Error</StatusBadge.Text></StatusBadge.Root>
</HStack>
</VStack>

Dot + Text

StatusBadge.Dot은 context에서 status와 type을 읽어 색상을 자동으로 결정합니다.

<HStack $css={{ gap: '$spacing-150', flexWrap: 'wrap' }}>
<StatusBadge.Root status="default" variant="tint">
  <StatusBadge.Dot />
  <StatusBadge.Text>Default</StatusBadge.Text>
</StatusBadge.Root>
<StatusBadge.Root status="success" variant="tint">
  <StatusBadge.Dot />
  <StatusBadge.Text>Success</StatusBadge.Text>
</StatusBadge.Root>
<StatusBadge.Root status="warning" variant="tint">
  <StatusBadge.Dot />
  <StatusBadge.Text>Warning</StatusBadge.Text>
</StatusBadge.Root>
<StatusBadge.Root status="error" variant="tint">
  <StatusBadge.Dot />
  <StatusBadge.Text>Error</StatusBadge.Text>
</StatusBadge.Root>
<StatusBadge.Root status="primary" variant="tint">
  <StatusBadge.Dot />
  <StatusBadge.Text>Primary</StatusBadge.Text>
</StatusBadge.Root>
<StatusBadge.Root status="informative" variant="tint">
  <StatusBadge.Dot />
  <StatusBadge.Text>Informative</StatusBadge.Text>
</StatusBadge.Root>
</HStack>

Icon + Text

StatusBadge.Icon은 context의 size에 따라 아이콘 크기를 자동 조절합니다.

<HStack $css={{ gap: '$spacing-150', flexWrap: 'wrap' }}>
<StatusBadge.Root status="success" variant="tint">
  <StatusBadge.Icon><IconCheckOutline /></StatusBadge.Icon>
  <StatusBadge.Text>완료</StatusBadge.Text>
</StatusBadge.Root>
<StatusBadge.Root status="warning" variant="tint">
  <StatusBadge.Icon><IconWarningOutline /></StatusBadge.Icon>
  <StatusBadge.Text>경고</StatusBadge.Text>
</StatusBadge.Root>
<StatusBadge.Root status="error" variant="tint">
  <StatusBadge.Icon><IconInformationOutline /></StatusBadge.Icon>
  <StatusBadge.Text>오류</StatusBadge.Text>
</StatusBadge.Root>
<StatusBadge.Root status="primary" variant="filled">
  <StatusBadge.Icon><IconSettingsOutline /></StatusBadge.Icon>
  <StatusBadge.Text>처리 중</StatusBadge.Text>
</StatusBadge.Root>
</HStack>

Loader + Text

비동기 처리 중 상태를 나타낼 때 사용합니다.

<HStack $css={{ gap: '$spacing-150', flexWrap: 'wrap' }}>
<StatusBadge.Root status="primary" variant="filled">
  <StatusBadge.Loader />
  <StatusBadge.Text>로딩 중</StatusBadge.Text>
</StatusBadge.Root>
<StatusBadge.Root status="default" variant="tint">
  <StatusBadge.Loader />
  <StatusBadge.Text>처리 중</StatusBadge.Text>
</StatusBadge.Root>
</HStack>

크기 설정

sm부터 xl까지 네 단계를 제공합니다.

<HStack $css={{ gap: '$spacing-200', alignItems: 'center', flexWrap: 'wrap' }}>
<StatusBadge.Root status="primary" variant="filled" size="sm">
  <StatusBadge.Dot /><StatusBadge.Text>sm (16px)</StatusBadge.Text>
</StatusBadge.Root>
<StatusBadge.Root status="primary" variant="filled" size="md">
  <StatusBadge.Dot /><StatusBadge.Text>md (20px)</StatusBadge.Text>
</StatusBadge.Root>
<StatusBadge.Root status="primary" variant="filled" size="lg">
  <StatusBadge.Dot /><StatusBadge.Text>lg (24px)</StatusBadge.Text>
</StatusBadge.Root>
<StatusBadge.Root status="primary" variant="filled" size="xl">
  <StatusBadge.Dot /><StatusBadge.Text>xl (30px)</StatusBadge.Text>
</StatusBadge.Root>
</HStack>

반응형 크기

size에 breakpoint 객체를 전달하면 화면 너비에 따라 크기가 변합니다.

<StatusBadge.Root status="success" variant="tint" size={{ mobile: 'sm', desktop: 'lg' }}>
<StatusBadge.Dot />
<StatusBadge.Text>반응형 — 리사이즈해보세요</StatusBadge.Text>
</StatusBadge.Root>

Icon Only 모드

iconOnly prop을 사용하면 padding이 제거되고 width = height가 되어 원형 아이콘 배지로 변환됩니다. status × type 색상이 유지됩니다.

<HStack $css={{ gap: '$spacing-200', alignItems: 'center', flexWrap: 'wrap' }}>
<StatusBadge.Root status="success" variant="filled" size="md" iconOnly>
  <StatusBadge.Dot />
</StatusBadge.Root>
<StatusBadge.Root status="error" variant="tint" size="md" iconOnly>
  <StatusBadge.Icon><IconInformationOutline /></StatusBadge.Icon>
</StatusBadge.Root>
<StatusBadge.Root status="primary" variant="outline" size="lg" iconOnly>
  <StatusBadge.Dot />
</StatusBadge.Root>
<StatusBadge.Root status="warning" variant="filled" size="xl" iconOnly>
  <StatusBadge.Loader />
</StatusBadge.Root>
</HStack>

드롭다운 트리거로 활용

render prop으로 <button>으로 변환하여 인터랙티브 트리거로 사용할 수 있습니다.

<StatusBadge.Root
status="success"
variant="tint"
render={<button />}
onClick={() => alert('상태 변경')}
>
<StatusBadge.Dot />
<StatusBadge.Text>활성</StatusBadge.Text>
<StatusBadge.Icon><IconCaretDownFilled /></StatusBadge.Icon>
</StatusBadge.Root>

$css로 토큰 기반 커스텀

<HStack $css={{ gap: '$spacing-200', flexWrap: 'wrap' }}>
{/* 최소 너비 지정 */}
<StatusBadge.Root status="primary" variant="tint" $css={{ minWidth: '80px', justifyContent: 'center' }}>
  <StatusBadge.Text>중앙 정렬</StatusBadge.Text>
</StatusBadge.Root>

{/* 커스텀 border radius */}
<StatusBadge.Root status="success" variant="filled" $css={{ borderRadius: '$radius-100' }}>
  <StatusBadge.Text>각진 배지</StatusBadge.Text>
</StatusBadge.Root>
</HStack>

Compound Components

공통 Props — $css, render, className, style는 모든 서브컴포넌트에서 지원됩니다. useRenderComponent 가이드 →

StatusBadge.Root

루트 배지 컴포넌트. useRenderComponent를 내부적으로 사용합니다. 기본 태그는 <div>입니다.

Prop

Type

StatusBadge.Dot

상태 표시 점. StatusBadge.Root context에서 status와 size를 읽어 색상과 크기를 자동 결정합니다. color, size, type을 직접 지정하면 context 값을 오버라이드합니다.

Prop

Type

StatusBadge.Icon

아이콘을 감싸는 컴포넌트. context의 size에 따라 아이콘 크기를 자동 조절합니다.

Prop

Type

StatusBadge.Text

텍스트를 감싸는 컴포넌트. 내부적으로 Typo를 사용하며, size에 맞는 typography variant와 status × type에 맞는 텍스트 색상을 자동 적용합니다.

Prop

Type

StatusBadge.Loader

로딩 인디케이터. 내부적으로 Loader를 사용합니다.

Prop

Type

스타일

Size Variants

Size	Height	Padding X	Gap	Icon Size	Typography
`sm`	16px	`spacing-100` (4px)	`spacing-50` (2px)	12px	`$body-1`
`md`	20px	`spacing-150` (6px)	`spacing-100` (4px)	12px	`$body-1`
`lg`	24px	`spacing-200` (8px)	`spacing-150` (6px)	14px	`$body-2`
`xl`	30px	`spacing-250` (10px)	`spacing-200` (8px)	16px	`$body-3`

Status × Type 색상 토큰

Status	Type	Background	Border	Text
`default`	`filled`	`gray-40`	`gray-40`	`white`
`default`	`tint`	`gray-10`	`border-1`	`text-3`
`default`	`outline`	`white`	`border-1`	`text-3`
`default`	`subtle`	—	—	`text-3`
`error`	`filled`	`support-error-3`	`support-error-3`	`white`
`error`	`tint`	`support-error-1`	`support-error-2`	`support-error-4`
`error`	`outline`	`white`	`support-error-2`	`support-error-4`
`warning`	`filled`	`support-warning-3`	`support-warning-3`	`white`
`warning`	`tint`	`support-warning-1`	`support-warning-2`	`support-warning-4`
`success`	`filled`	`support-success-3`	`support-success-3`	`white`
`success`	`tint`	`support-success-1`	`support-success-2`	`support-success-4`
`primary`	`filled`	`support-info-3`	`support-info-3`	`white`
`primary`	`tint`	`support-info-1`	`support-info-2`	`support-info-4`
`informative`	`filled`	`gray-90`	`gray-90`	`white`
`informative`	`tint`	`background-2`	`border-2`	`text-2`

Dot 자동 매핑

StatusBadge.Dot은 badge type이 filled이면 항상 white를, 그 외에는 status별 색상을 사용합니다.

Status	Dot Color (non-filled)
`default`	`gray`
`informative`	`black`
`primary`	`purple`
`success`	`green`
`warning`	`orange`
`error`	`red`

Badge size와 Dot size 자동 매핑:

Badge Size	Dot Size
`sm`	`xs` (6px)
`md`	`xs` (6px)
`lg`	`sm` (8px)
`xl`	`md` (10px)

On this page