BarChart

Examples #

'use client';

import { BarChart } from '@coreux/ui';

export default function Grouped() {
  return (
    <div role="group" aria-label="Illustrative quarterly adoption and savings indices; independent measures, not percentages of a whole." style={{ width: 340, background: '#F4F1E9' }}>
      <BarChart
        width={340}
        height={260}
        categories={[
          { id: 'q1', label: 'Q1' },
          { id: 'q2', label: 'Q2' },
          { id: 'q3', label: 'Q3' },
          { id: 'q4', label: 'Q4' },
        ]}
        series={[
          { id: 'adoption', label: 'Adoption', values: [40, 55, 62, 72] },
          { id: 'savings', label: 'Savings', values: [20, 28, 30, 40] },
        ]}
      />
    </div>
  );
}

Choosing a presentation #

Use grouped bars to compare independent measures within each category, stacked bars for non-overlapping parts of a total, and a single series for one measure over a short sequence.

All examples use illustrative data. In Stacked, “Planned” means remaining work and “Actual” means completed work, both in hours. If planned means the original estimate instead, compare those values with grouped bars rather than adding them.

• Grouped preserves the four-quarter, two-series seed at 340 × 260 px.
• Stacked preserves the three-category, two-series seed at 340 × 260 px.
• SingleSeries preserves the three-month revenue seed at 340 × 220 px without a legend.
• Horizontal · dark adds a 480 × 260 px view of that same revenue dataset, with a dark surface, value labels, and an explicit domain.

Use orientation="horizontal" to read categories along the left edge. It works with both layouts. The horizontal plot starts 112 px from the left; the vertical plot starts at 52 px. Longer labels still need a visual check: orientation does not provide automatic wrapping, and value labels near the right edge can clip.

The original seed data, chart dimensions, and layout/legend choices are retained. Their 24 px wrapper padding is omitted; the documentation canvas supplies surrounding space. Each complete example adds a client directive and a named group for illustrative units and context. The light surface remains in the copied source.

Data & validation #

Validation runs when the component renders, not just in TypeScript. Invalid input throws an error; it is not silently repaired. Start with 1–8 categories and 1–6 series. Category IDs must be unique within categories and series IDs within series. IDs must be non-empty strings; labels must contain one non-empty text line.

Every series needs exactly one value per category, in category order. Values must be finite, non-negative numbers; negative bars and missing values are unsupported. Zero is valid and produces a zero-size bar. Stacked values must also sum to finite totals.

Keep a zero baseline

An explicit domain requires min: 0 and a finite max greater than zero. For grouped charts, max must include the largest individual value; for stacked charts, it must include the largest category total. Otherwise rendering throws. Without a domain, max is Math.max(1, maximum * 1.1). Automatic padding must remain finite too.

For the supplied seeds, the grouped maximum value is 72 and the stacked maximum total is 115. Explicit domains such as { min: 0, max: 80 } and { min: 0, max: 130 }, respectively, include those values. Use a shared explicit domain when comparing multiple charts. Stacked layout adds values; it does not convert them to percentages.

Budget space for the legend

Width must be finite and at least 280 px; height must be finite and at least 200 px. Height includes the legend. A single series can show or omit it, but multiple series cannot hide the legend. The component uses up to two legend columns and reserves 56 px per row.

These are validation floors, not guarantees that your labels fit. Increase dimensions for dense data and long labels. Category text has no wrapping logic, and capsule legend text can clip. Use fewer categories or shorter labels when possible.

Appearance & motion #

Field mode chooses the surrounding visual language

fieldMode="light" uses navy/slate text and pale grid lines. fieldMode="dark" uses ivory/pale-steel text and slate grid lines. BarChart itself has a transparent background, so pair the mode with a matching outer surface, as the examples do. The categorical bar palette follows series order and stays the same in both modes.

The video-derived family distinguishes field mode from semantic tone. Components such as Capsule use neutral, accent, muted, positive, warning, or error to express meaning. BarChart does not expose tone; its legend capsules use neutral. This differs from the marketing family’s ink/ivory text tones.

BarChart uses inline styles and SVG attributes. It exposes no className, style, custom palette, or arbitrary HTML-attribute passthrough. Utility classes on a wrapper can arrange the surrounding layout; they do not provide an API to restyle the chart’s internal geometry, typography, or bars. Use the supported props and the documented library stylesheet/fonts.

Omitted progress props show the completed state

Remotion is not required. This is an ordinary React component with no internal clock: omitting its progress props renders fully grown bars, visible labels/legend, and full opacity. It does not start an animation automatically.

If you animate it yourself, finite progress values clamp to 0–1; NaN and infinity throw. A barProgress array needs one entry per bar, in category-major then series order. A groupProgress array must match the category count and a seriesProgress array the series count. These latter channels control opacity. emphasis needs an existing category ID, series ID, or both, plus finite progress. Respect reduced-motion preferences and retain readable data context.

Props #

The four required inputs are dimensions, categories, and series. Defaults below come from the installed component’s parameter initializers; the domain fallback and runtime limits are explained above.

Accessibility & layout #

The chart exposes an image role with a generated label naming its layout, orientation, and series. A linked hidden description lists every category’s values, plus category totals for stacked charts. Numbers display with at most three decimal places. The SVG is hidden from assistive technology; the chart is not an interactive data table and has no hover, selection, or keyboard controls.

The examples’ surrounding groups identify the illustrative units; the same context is visible above the preview. In a published composition, add a visible title, timeframe, units, source, and a short takeaway. For exact data lookup, also offer a text table or download. Do not rely only on color or assume labels remain readable after scaling.

The supplied width and height are fixed CSS pixels, and the component clips content outside its bounds. It has no responsive breakpoints. Fit to canvas scales the entire preview without changing its props or copied source; text scales too. Actual size preserves the authored dimensions inside a focusable, horizontally scrollable region. These controls belong to the documentation, not the package.

For one headline metric, use StatBlock. For an authored social narrative that combines metrics with a message, see SocialCarouselSlide. Use bars for comparison on a shared scale, and a table when readers need precise lookups across many values.

Consumer setup #

Browsing, previews, and copying are public. Installing the private @coreux/ui package requires repository read access and permission to use the bundled CoreUX brand fonts.

Follow the one-time installation guide for the pinned Git dependency, Tailwind v4 stylesheet setup, fonts, and troubleshooting. Keep the 'use client' directive in each example; no provider is required.

The quick start walks through a copied StatBlock in a minimal app.

Source & revision #

This reference targets @coreux/ui version 0.1.0 at 06f42fd. Types come from its installed declarations; explanations and defaults are checked against this implementation.

Revision and upgrade notes · Contribution and coverage guide