스탯 카드

대시보드에서 단일 지표(라벨+값)를 한 눈에 보여주는 표시 카드다. 데이터 fetch·계산·포맷은 호출자 몫이고, 카드는 넘겨받은 값을 배치·강조만 한다. 여러 장을 나열하는 격자·간격은 Grid·Stack이 맡는다.

상태

총 사용자

활성 사용자 전체

card (기본)

내 결재 대기

row

이번달 처리

결재 완료 건수

아이콘 없음

진행중

레이아웃은 layout prop으로: card(아이콘 위, 기본)와 row(아이콘 좌측). 격자 배치는 Grid로.

활용 방법

그리드 배치

여러 지표를 나란히 보여줄 때는 Grid와 조합한다. 카드 자체는 레이아웃을 담당하지 않는다.

Preview

총 사용자

활성 사용자 전체

진행중 작업

접수~진행 단계

tsx

<Grid columns={2} gap="sm">
  <StatCard icon={<Users size={16} />} value={37} label="총 사용자" description="활성 사용자 전체" />
  <StatCard icon={<Target size={16} />} value={32} label="진행중 작업" description="접수~진행 단계" />
</Grid>

세로 목록 (row)

결재함·사이드바처럼 수직으로 나열할 때는 row 레이아웃을 쓴다.

Preview

내 결재 대기

진행중

이번달 처리

tsx

<StatCard layout="row" icon={<Inbox size={16} />} value={0} label="내 결재 대기" />
<StatCard layout="row" icon={<Clock size={16} />} value={16} label="진행중" />
<StatCard layout="row" icon={<CheckCircle size={16} />} value={22} label="이번달 처리" />

이전 기간 비교

trend + comparison 조합으로 이전 기간 대비 수치를 함께 보여준다.

Preview

Total Events

+20%

3225 last week

Total Hours

-8%

38.2hr42.0 last week

Focus Time

+12%

16.8hr14.4 last week

tsx

<StatCard
  label="Total Events"
  value={32}
  trend={{ direction: "up", label: "+20%" }}
  comparison="25 last week"
/>

추세 (trend)

전월 대비 변화를 함께 보여줄 때 trend를 쓴다. 라벨 우측에 pill badge로 표시된다. up=success, down=danger.

Preview

총 사용자

+12%

37from 32

진행중 작업

-1.97%

접수~진행 단계

tsx

<StatCard
  icon={<Users size={16} />}
  value={37}
  label="총 사용자"
  comparison="from 32"
  trend={{ direction: "up", label: "+12%" }}
/>

단위 · 부호 (prefix · suffix · sign)

금액은 valuePrefix, 퍼센트는 valueSuffix. sign을 주면 값 전체에 색과 +/- 부호가 붙는다.

Preview

평균 단가

+ $7.26

평균 단가

- $7.26

tsx

<StatCard value={7.26} label="평균 단가" valuePrefix="$" sign="positive" />
<StatCard value={7.26} label="평균 단가" valuePrefix="$" sign="negative" />

스파크라인 차트 (chart)

chart prop 에 ReactNode 를 넘기면 카드 우하단에 배치된다. 차트 라이브러리는 호출자가 선택한다.

Preview

Productive Time / Day

+23%

12.4 hr

Focused Time / Day

+18%

8.5 hr

Available Time / Day

+15%

6.5 hr

tsx

<StatCard
  label="Productive Time / Day"
  value="12.4"
  valueSuffix=" hr"
  trend={{ direction: "up", label: "+23%" }}
  chart={<MySparkline data={data} />}
>

대시보드 KPI (chart + 반응형 값)

값·접두·접미 텍스트는 모바일(<640px)에서 한 단계 작아진다: 좁은 격자 카드에서 숫자+단위가 차트와 겹치지 않게. 브라우저 폭을 좁혀보면 크기 변화를 확인할 수 있다.

Preview

7월 매출

1,234만원

7월 손익

+ 890만원

7월 주문액

562만원

미납 수강료

340만원

진행중 결재

12건

tsx

// 모바일에서 값은 text-2xl, sm 이상에서 text-3xl 복귀 (컴포넌트가 자동 처리)
<StatCard
  icon={<Banknote size={16} />}
  tone="info"
  label="7월 매출"
  value="1,234만"
  valueSuffix="원"
  chart={<Sparkline data={daily} />}
/>

로딩

데이터를 불러오는 동안 loading을 주면 값·아이콘 자리가 skeleton으로 대체된다.

Preview

총 사용자

내 결재 대기

tsx

<StatCard icon={<Users size={16} />} value={undefined} label="총 사용자" loading />

언제 쓰지 않나

· 여러 지표가 행·열로 비교되어야 할 때 → DataGrid를 쓴다.
· 차트·그래프가 필요한 복합 지표 → 카드 안에 차트를 직접 조합한다(StatCard 범위 밖).
· 상태 레이블만 필요할 때 → Badge로 충분하다.

속성

이름	타입	기본값	설명
label	string	-	카드 정체성 텍스트: 필수
value	number \| string \| undefined	-	메인 값. undefined면 '-' 폴백
layout	"card" \| "row"	"card"	card=아이콘 위·값 아래, row=아이콘 좌측·값 큼
icon	ReactNode	-	없으면 아이콘 영역 자체를 렌더하지 않는다
tone	"neutral" \| "info" \| "success" \| "warning" \| "danger"	"neutral"	아이콘 박스 배경 의미색. icon 없으면 무시
description	string	-	값 아래 보조 설명
comparison	string	-	값 옆 인라인 비교 텍스트 ("from 30.4%")
trend	{ direction: "up" \| "down", label: string }	-	추세 pill badge: 라벨 우측 상단. up=success, down=danger
sign	"positive" \| "negative"	-	값 색·부호: positive=green "+", negative=red "-"
valuePrefix	string	-	값 앞 단위 (₩, $ 등)
valueSuffix	string	-	값 뒤 단위 (건, % 등)
chart	ReactNode	-	card 레이아웃 우하단 슬롯: 스파크라인 등. row 레이아웃에선 무시
onClick	MouseEventHandler	-	클릭 핸들러. 있으면 button으로 렌더되고 hover·active 반응
href	string	-	링크. onClick보다 우선(a로 렌더)
loading	boolean	false	skeleton 상태: 값·아이콘 자리를 pulse로