FunnelChart

SVG로 그리는 깔때기·피라미드 차트 컴포넌트.

개요

첫 시리즈의 행을 단계(세그먼트)로 그립니다. 세그먼트 높이는 값에 비례하고, 값이 큰 항목이 넓은 쪽에 옵니다.

주요 특징

• ✅ 도형: shape로 깔때기("funnel")·피라미드("pyramid")
• ✅ 깔때기 목: neckWidth·neckHeight 비율
• ✅ 숫자 서식: thousandSeparator로 툴팁 값에 구분자
• ✅ 범례 토글: 범례 항목을 눌러 세그먼트 숨김·표시
• ✅ 컨테이너: 제목·도구·검색 폼·접기
• ✅ 빈 상태: 데이터가 없으면 안내 문구

기본 사용

series에 시리즈를 넘깁니다. 첫 시리즈만 쓰고, xKey는 단계 이름, yKey는 값 필드입니다. 기본 도형은 깔때기이고 값 내림차순으로 위부터 쌓습니다. 범례는 위에 놓이고 그리는(정렬된) 순서로 나열합니다.

import { FunnelChart } from "@vortex/ui-cals"
 
const series = [
  {
    data: [
      { stage: "방문", count: 5000 },
      { stage: "관심", count: 3500 },
      { stage: "검토", count: 2000 },
      { stage: "구매", count: 800 },
      { stage: "재구매", count: 300 },
    ],
    xKey: "stage",
    yKey: "count",
    name: "전환",
  },
]
 
<FunnelChart series={series} />

피라미드 (shape=“pyramid”)

꼭짓점이 위인 삼각형입니다. 값 오름차순이라 작은 값이 위에 옵니다.

<FunnelChart series={series} shape="pyramid" />

깔때기 목 (neckWidth, neckHeight)

목의 너비·높이를 전체 대비 비율(0~1)로 정합니다. 기본은 0.3·0.25이고 shape="funnel"에서만 씁니다.

<FunnelChart series={series} neckWidth={0.15} neckHeight={0.3} />

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

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

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

천 단위 구분자 (thousandSeparator)

툴팁 값에 걸립니다. 세그먼트에 마우스를 올려 확인합니다.

<FunnelChart series={series} thousandSeparator />

색상 (colors)

행(입력) 순서대로 쓰고, 모자라면 처음부터 다시 씁니다. 정렬해도 항목마다 색이 그대로라 깔때기와 피라미드에서 같은 색이고, 범례 색도 같습니다. 이 예는 입력 순서가 값 순서와 다른 데이터라, 위에서부터가 아니라 행 순서(구매·방문·재구매·관심·검토)대로 색이 붙습니다.

const shuffled = [
  {
    data: [
      { stage: "구매", count: 800 },
      { stage: "방문", count: 5000 },
      { stage: "재구매", count: 300 },
      { stage: "관심", count: 3500 },
      { stage: "검토", count: 2000 },
    ],
    xKey: "stage",
    yKey: "count",
    name: "전환",
  },
]
 
<FunnelChart
  series={shuffled}
  colors={["#0ea5e9", "#22c55e", "#f59e0b", "#ef4444", "#8b5cf6"]}
/>

범례 클릭 토글 (legendToggle)

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

<FunnelChart series={series} legendToggle />

포인트 클릭 (onPointClick)

세그먼트를 누르면 단계 이름·인덱스(입력 순서), X값(단계 이름)·Y값(값), 클릭한 세그먼트의 원본 행(payload)을 넘깁니다. payload는 series[0].data[j] 그 객체입니다.

세그먼트를 클릭하세요

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

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

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

import { FunnelChart, Button, FormCol, Text } from "@vortex/ui-cals"
 
<FunnelChart
  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이 있을 때 씁니다. 위는 접힌 채 시작하고, 아래는 접고 펼 수 없습니다.

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

빈 상태

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

<FunnelChart series={[]} />

API Reference

Props

FunnelChartSeries

FunnelChartPointClickData

행 타입 (Row)

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

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

접근성

권장 사항

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

관련 컴포넌트

• PieChart: 파이·도넛 차트
• BarChart: 막대 차트