PieChart

recharts 기반 파이·도넛 차트 컴포넌트.

개요

첫 시리즈의 행을 조각으로 그립니다. innerRadius를 주면 도넛이 됩니다.

주요 특징

• ✅ 파이·도넛: innerRadius로 가운데를 비운다
• ✅ 데이터 라벨: showDataLabel, dataLabelPosition(inside·outside), 시리즈의 labelKey
• ✅ 숫자 서식: thousandSeparator로 툴팁과 숫자 라벨에 구분자
• ✅ 범례 토글: 범례 항목을 눌러 조각 숨김·표시
• ✅ 컨테이너: 제목·도구·검색 폼·접기
• ✅ 빈 상태: 데이터가 없으면 안내 문구

기본 사용

series에 시리즈를 넘깁니다. 첫 시리즈만 쓰고, xKey는 항목 이름, yKey는 값 필드입니다.

import { PieChart } from "@vortex/ui-cals"
 
const series = [
  {
    data: [
      { category: "데스크톱", value: 45, note: "절반 가까이" },
      { category: "모바일", value: 30 },
      { category: "태블릿", value: 15 },
      { category: "기타", value: 10 },
    ],
    xKey: "category",
    yKey: "value",
    name: "접속 기기",
  },
]
 
<PieChart series={series} />

도넛 (innerRadius)

% 문자열은 바깥 반지름 대비입니다("40%"면 구멍 반지름이 바깥 반지름의 0.4). 숫자는 px입니다. 기본 0이면 파이입니다. 바깥 반지름은 outerRadius(기본 "80%")로 정합니다.

<PieChart series={series} innerRadius="40%" />

범례·툴팁 끄기 (legend, tooltip)

둘 다 기본으로 켜져 있습니다.

<PieChart series={series} legend={false} tooltip={false} />

데이터 라벨 (showDataLabel, dataLabelPosition, labelKey)

위는 기본으로 항목 이름을 조각 바깥("outside")에 씁니다. 아래는 labelKey로 note 필드를 조각 안("inside")에 쓰고, 값이 비면 값을 씁니다.

<PieChart series={series} showDataLabel height={300} />
<PieChart
  series={[{ ...series[0], labelKey: "note" }]}
  showDataLabel
  dataLabelPosition="inside"
  height={300}
/>

천 단위 구분자 (thousandSeparator)

툴팁과 숫자 데이터 라벨에 걸립니다. 이 예는 labelKey로 값 필드를 라벨로 씁니다.

const largeSeries = [
  {
    data: [
      { category: "데스크톱", value: 45200 },
      { category: "모바일", value: 30150 },
      { category: "태블릿", value: 15800 },
      { category: "기타", value: 9850 },
    ],
    xKey: "category",
    yKey: "value",
    name: "접속 수",
    labelKey: "value",
  },
]
 
<PieChart series={largeSeries} thousandSeparator showDataLabel />

색상 (colors)

항목 순서대로 쓰고, 모자라면 처음부터 다시 씁니다.

<PieChart
  series={series}
  colors={["#0ea5e9", "#22c55e", "#f59e0b", "#ef4444"]}
/>

범례 클릭 토글 (legendToggle)

범례 항목을 누르면 그 조각을 원에서 빼고 남은 항목이 360°를 나눕니다. 숨긴 항목은 범례에 흐리게 남아 다시 누르면 돌아옵니다. 이름이 같은 항목도 따로 그리고 따로 숨기며, 범례·툴팁에는 그 이름이 그대로 보입니다. 기본으로 켜져 있고 legendToggle={false}로 끕니다.

<PieChart series={series} legendToggle />

포인트 클릭 (onPointClick)

조각을 누르면 항목 이름·인덱스, X값(항목 이름)·Y값(값), 클릭한 조각의 원본 행(payload)을 넘깁니다. payload는 series[0].data[j] 그 객체이고, 앞 항목을 범례로 숨겨도 인덱스는 원래 순서를 따릅니다.

조각을 클릭하세요

const [clicked, setClicked] = useState<PieChartPointClickData | null>(null)
 
<PieChart series={series} onPointClick={setClicked} />

제목·도구·검색 폼 (title, actions, searchContent)

title을 주면 접고 펼 수 있는 머리가 생깁니다. actions는 머리 오른쪽에, searchContent는 차트 위 검색 폼 자리에 그립니다. 검색 폼은 24칸 격자이고 searchColumns·searchColGap·searchRowGap으로 바꿉니다. title이 없으면 actions·검색 폼·접기 props는 쓰이지 않습니다.

import { PieChart, Button, FormCol, Text } from "@vortex/ui-cals"
 
<PieChart
  series={series}
  title="접속 기기 비율"
  actions={
    <>
      <Button>조회</Button>
      <Button variant="outline">초기화</Button>
    </>
  }
  searchContent={
    <>
      <FormCol span={12}><Text label="기간" placeholder="2025-01 ~ 2025-06" /></FormCol>
      <FormCol span={12}><Text label="지역" placeholder="지역명" /></FormCol>
    </>
  }
/>

접기 (defaultCollapsed, collapseDisabled)

title이 있을 때 씁니다. 위는 접힌 채 시작하고, 아래는 접고 펼 수 없습니다.

<PieChart series={series} title="접힌 채 시작" defaultCollapsed />
<PieChart series={series} title="접기 막기" collapseDisabled />

빈 상태

데이터가 없으면 emptyText를 보입니다.

<PieChart series={[]} />

API Reference

Props

PieChartSeries

PieChartPointClickData

행 타입 (Row)

Props·Series·PointClickData는 행 타입 Row를 받습니다(기본 Record<string, unknown>). series의 data에서 추론되므로 onPointClick의 payload를 형 변환 없이 읽을 수 있습니다.

type SalesRow = { category: string; value: number; code: string }
 
const rows: SalesRow[] = [/* … */]
 
<PieChart
  series={[{ data: rows, xKey: "category", yKey: "value" }]}
  onPointClick={(d) => openDetail(d.payload.code)} // d.payload: SalesRow
/>

접근성

권장 사항

• ✅ recharts accessibilityLayer 자동 활성화
• ✅ 빈 차트 시 대체 텍스트(emptyText) 제공
• ✅ 범례 항목은 aria-pressed 버튼이라 키보드로 토글할 수 있다

관련 컴포넌트

• FunnelChart: 깔때기·피라미드 차트
• BarChart: 막대 차트