• Introduction
  • Usage in commercial projects
  • Limitations
  • Demo
  • Supporting reads
  • API
    • Square vs linear fill
    • Directional filling
    • Total and Data Display
    • Colors
    • Fonts and other styling
  • Installing
    • Usage
    • Updating
  • Contributing
  • Developing
    • Testing
    • Building
    • Merging

As an American assimilating into Norway and the way of life, I'd like to think Norwegians would be proud of me for this one:

Waffles are better than Pies

🧇 > 🥧

There, I said it...and it's true.

Pies and donuts are harder to read, take longer to evaluate the meaning behind the visualization, and tend to take up more space.

Waffle charts can display more in the same amount of space at a larger, easier to read size. It provides a better graphical and textual representation of proportions. Thanks to a 10 x 10 grid, the user can quickly assess the overall portions and then drill down to the 1%.

My personal opinion is that after three values, a bar chart (stackable-bar-chart coming soon) is better at showing the data relations rather than the waffle, which is why I've capped the values to three for this component. It also helps to keep each input prop primitive.

This is a zero-dependency library built with React, Typescript & Vite.

No D3 only HTML, CSS, and JS/TS.

🚀 v2.0.0: Now supporting three quantities!

If you are using this in a commercial project, please consider leaving a donation/tip. Cheers!

• Requires browser support for CSS grid and flexbox.
• Requires browser support for CSS clamp().

Live demo via Storybook coming soon.

• 📄 Storytelling with Data
• 📄 The Issue with Pie (Donut) Chart
• 📄 The Worst Chart In The World
• 📄 Waffles vs Pies - A visualization showdown!
• 📄 Your Dashboard Needs a Waffle Chart

The chart will render with just the default props.

Square (default) fill will fill partA values in a square shape with any remainders above on the next row. Linear will fill the entire row first then move onto the next row. Square fill is slightly more logic, but performance difference shouldn't be noticeable.

Toggling the vertical and horizontal fill directions will change the position where partA value fills from. The label will follow the vertical fill setting.

Toggling these values will show/hide the calculations for total and percentages/counts.

You can pass in colors via props or just override in :root or some scope above the component for the following:

• --bg-total: color for total, the fallback is slategray
• --bg-square: color for partB squares, the fallback is cadetblue
• --bg-square-valued: color for partA squares, the fallback is palevioletred

The fallbacks were chosen as they satisfy color contrast accessibility for both white and black backgrounds according to WCAG AA standards for Large Text, UI Components, & Graphical Objects.

The component will inherit the font from your app or can be modified by selecting it's class. Additional special stylings can be applied by selecting the right classes.

Using NPM:

npm i waffle-chart

Using Yarn:

yarn add waffle-chart

I recommend as a practice to wrap components like this in your own wrapper component that exposes the same API. This way you aren't married to this library and can easily swap it out without breaking consumers of your component.

// Import the CSS at the highest scope possible without coupling e.g. Shared or Vendor or Lib directory.
import 'node_modules/waffle-chart/dist/style.css';

import type { WaffleChartProps } from 'waffle-chart';
import { WaffleChart } from 'waffle-chart';

type Props = WaffleChartProps;

const MyChart: React.FC<Props> = (props: Props) => <WaffleChart {...props}/>

export default MyChart;

For Remix projects just import the style url in the links at the root.tsx.

import waffleChartStylesUrl from 'node_modules/waffle-chart/dist/style.css';

export const links: LinksFunction = () => [
    {
        rel: 'stylesheet',
        href: waffleChartStylesUrl,
    },
];

npm

npm update

yarn

yarn upgrade waffle-chart@^

This package is free for you to clone and change to your needs in accordance with the MIT license terms. If you want to contribute back to this codebase for improvements, please fork it, create an issue and then initiate a pull request that details the changes and problem or enhancement. Thanks! 🍻

Starting development server:

yarn dev

Testing methodology follows the testing-library guiding principles and focusing user interactions and integration testing.

Latest coverage report:

Test Files  6 passed (6)
     Tests  13 passed (13)
  Start at  12:41:38
  Duration  2.26s (setup 2ms, collect 1.08s, tests 395ms)

-------------|---------|----------|---------|---------|---------------------------
File         | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
-------------|---------|----------|---------|---------|---------------------------
All files    |   98.52 |    87.64 |   95.65 |   98.52 |                           
 Chart       |     100 |      100 |     100 |     100 | 
  index.tsx  |     100 |      100 |     100 |     100 | 
 ChartSquare |     100 |      100 |     100 |     100 | 
  index.tsx  |     100 |      100 |     100 |     100 | 
 DataDisplay |     100 |      100 |     100 |     100 | 
  index.tsx  |     100 |      100 |     100 |     100 | 
 Total       |     100 |      100 |     100 |     100 | 
  index.tsx  |     100 |      100 |     100 |     100 | 
 WaffleChart |   97.86 |    84.93 |   94.11 |   97.86 | 
  index.tsx  |   97.86 |    84.93 |   94.11 |   97.86 | 79-80,106,111,116,199,307
-------------|---------|----------|---------|---------|---------------------------

Testing is built and run with:

• Vitest
• React-Testing-Library

You'll notice very sparse snapshots for each component and a focus on the integrations.

Run tests once:

yarn test

Run tests and watch for changes:

yarn watch

Check coverage:

yarn coverage

Run Vitest UI:

yarn testui

yarn build

See Contributing.