BarChart

recharts 기반 막대 차트 컴포넌트.

개요

시리즈 데이터를 막대로 그립니다. 기본은 세로 막대이고, orientation으로 가로 막대를, stacked로 누적 막대를 고릅니다.

주요 특징

• ✅ 다중 시리즈: 시리즈마다 막대 하나. 여러 시리즈의 같은 x는 한 묶음으로 나란히 그리고, 한 시리즈 안의 같은 x는 따로 그린다. 이름이 같은 시리즈도 따로 그리고 따로 숨기며, 범례·툴팁에는 그 이름이 그대로 보인다
• ✅ 방향·누적: orientation="horizontal", stacked, 둘을 함께 써도 된다
• ✅ 데이터 라벨: showDataLabel, dataLabelPosition(값 방향 기준 이름), 시리즈별 labelKey
• ✅ 모서리: borderRadius. 누적이면 양수·음수를 따로 쌓고, 범주마다 양수 쪽·음수 쪽 끝 조각(보이는 시리즈 중 그 부호의 값을 가진 마지막)의 끝만 둥글린다
• ✅ 숫자 서식: thousandSeparator, 축 눈금 포맷터
• ✅ 범례 토글: 범례 항목을 눌러 시리즈 숨김·표시
• ✅ 컨테이너: 제목·도구·검색 폼·접기
• ✅ 빈 상태·음수: 데이터가 없으면 안내 문구, 음수면 값 축이 0을 지나도록 넓어진다

기본 사용

series에 시리즈 배열을 넘깁니다. 각 시리즈는 행 배열(data)과 X·Y 값을 읽을 필드 키(xKey, yKey)를 가집니다.

import { BarChart } from "@vortex/ui-cals"
 
const multiSeries = [
  {
    data: [
      { quarter: "Q1", value: 4500 },
      { quarter: "Q2", value: 5200 },
      { quarter: "Q3", value: 4800 },
      { quarter: "Q4", value: 6100 },
    ],
    xKey: "quarter",
    yKey: "value",
    name: "제품 A",
  },
  // 제품 B, 제품 C …
]
 
<BarChart series={multiSeries} />

가로 막대 (orientation)

orientation="horizontal"이면 범주 축이 세로, 값 축이 가로가 됩니다. 기본은 "vertical"입니다.

<BarChart series={multiSeries} orientation="horizontal" />

누적 막대 (stacked)

시리즈를 한 막대에 쌓습니다. 위는 세로, 아래는 가로 누적입니다.

<BarChart series={multiSeries} stacked height={260} />
<BarChart series={multiSeries} orientation="horizontal" stacked height={260} />

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

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

<BarChart series={multiSeries} legend={false} tooltip={false} />

데이터 라벨 (showDataLabel, dataLabelPosition)

위치는 "outside"(막대 끝 바깥)·"insideEnd"(끝 안쪽)·"center"·"insideStart"(시작 안쪽) 중에서 고릅니다. 값 방향 기준이라 가로 막대에도 같은 이름을 씁니다. 지정하지 않으면 누적은 "center", 아니면 "outside"입니다. 안쪽 라벨은 막대 위에서 읽히는 글자색입니다.

<BarChart series={multiSeries} showDataLabel height={260} />
<BarChart
  series={multiSeries}
  orientation="horizontal"
  showDataLabel
  dataLabelPosition="insideEnd"
  height={260}
/>

데이터 라벨 문구 (labelKey)

시리즈에 labelKey를 주면 그 필드를 라벨로 씁니다. 값이 비면 막대 값을 씁니다.

const labeledSeries = [
  {
    data: [
      { month: "1월", sales: 350, note: "저조" },
      { month: "2월", sales: 480, note: "" },
      { month: "3월", sales: 620, note: "목표 달성" },
      { month: "4월", sales: 410, note: "" },
    ],
    xKey: "month",
    yKey: "sales",
    name: "매출",
    labelKey: "note",
  },
]
 
<BarChart series={labeledSeries} showDataLabel />

천 단위 구분자 (thousandSeparator)

값 축 눈금, 숫자 데이터 라벨, 툴팁에 함께 걸립니다. 축 포맷터를 주면 축은 그쪽이 우선합니다.

<BarChart series={multiSeries} thousandSeparator showDataLabel />

축 눈금 서식 (xAxisTickFormatter, yAxisTickFormatter)

xAxisTickFormatter는 범주 축, yAxisTickFormatter는 값 축에 걸립니다. 가로 막대에서도 같습니다.

<BarChart
  series={multiSeries}
  xAxisTickFormatter={(v) => `2026 ${v}`}
  yAxisTickFormatter={(v) => `${v}만원`}
/>

축별 격자 (showXAxisGrid, showYAxisGrid)

X는 범주 축, Y는 값 축입니다. 둘 다 기본으로 보입니다. 가로 막대에서는 X축 격자가 가로선, Y축 격자가 세로선이 됩니다.

<BarChart series={multiSeries} showXAxisGrid={false} height={260} />
<BarChart series={multiSeries} orientation="horizontal" showYAxisGrid={false} height={260} />

모서리 둥글기 (borderRadius)

누적하지 않으면 네 모서리를 모두 둥글립니다. 누적하면 양수와 음수를 따로 쌓고, 범주마다 양수 쪽·음수 쪽 끝 조각(보이는 시리즈 중 그 부호의 값을 가진 마지막)의 끝만 둥글립니다. 기본은 0입니다.

<BarChart series={multiSeries} borderRadius={6} height={260} />
<BarChart series={multiSeries} stacked borderRadius={6} height={260} />

색상 (colors)

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

<BarChart series={multiSeries} colors={["#f59e0b", "#8b5cf6", "#10b981"]} />

범례 클릭 토글 (legendToggle)

범례 항목을 누르면 시리즈를 숨기고, 다시 누르면 보입니다. 숨긴 항목은 범례에 흐리게 남습니다. 이름이 같은 시리즈도 따로 숨깁니다. 시리즈 구성이 바뀌어 같은 자리에 이름이 다른 시리즈가 오면 숨김이 풀립니다. 기본으로 켜져 있고 legendToggle={false}로 끕니다.

<BarChart series={multiSeries} legendToggle />

포인트 클릭 (onPointClick)

막대를 누르면 시리즈 이름·인덱스, X·Y값, 클릭한 막대의 원본 행(payload)을 넘깁니다. payload는 series[i].data[j] 그 객체라 차트가 쓰지 않는 필드도 그대로 들어 있습니다.

막대를 클릭하세요

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

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

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

import { BarChart, Button, FormCol, Text } from "@vortex/ui-cals"
 
<BarChart
  series={multiSeries}
  title="분기별 매출"
  actions={
    <>
      <Button>조회</Button>
      <Button variant="outline">초기화</Button>
    </>
  }
  searchContent={
    <>
      <FormCol span={12}><Text label="연도" placeholder="2025" /></FormCol>
      <FormCol span={12}><Text label="제품" placeholder="제품명" /></FormCol>
    </>
  }
/>

접기 (defaultCollapsed, collapseDisabled)

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

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

음수 데이터

값 축이 음수까지 넓어지고 0 눈금을 지납니다. 양 끝에 여유를 두어 끝 라벨이 잘리지 않습니다. 음수 막대는 0에서 아래(가로 막대는 왼쪽)로 뻗습니다. 누적하면 양수는 0 위로, 음수는 0 아래로 따로 쌓습니다.

<BarChart series={profitSeries} showDataLabel height={260} />
<BarChart series={profitSeries} orientation="horizontal" showDataLabel height={260} />

빈 상태

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

<BarChart series={[]} />

API Reference

Props

BarChartSeries

BarChartPointClickData

행 타입 (Row)

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

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

접근성

권장 사항

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

관련 컴포넌트

• LineChart: 라인 차트
• ParetoChart: 파레토 차트