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
andflexbox
. - 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.
Prop | Type | Default | Notes |
---|---|---|---|
partA | number | 0 | this is the quantity, % is calculated by component |
partB | number | 0 | this is the quantity, % is calculated by component |
partC | number | 0 | this is the quantity, % is calculated by component |
displayPrecision | number | 0 | number of decimals for quantity and percentage |
partAlabel | string | 'A' | |
partBlabel | string | 'B' | |
partClabel | string | 'C' | |
rounding | 'nearest', 'up', 'down' | 'nearest' | up for any amount over the whole, down if under a whole |
isFilledFromTop | boolean | false | |
isFilledFromLeft | boolean | false | |
isSquareFill | boolean | true | can fill in linear by row if false |
isAnimatedFill | boolean | true | fade in color vs. instant change |
showDataDisplay | boolean | true | |
showTotal | boolean | false | |
partAColor | string | undefined | can take any CSS color (hsl, rgb, hex, ...) |
partBColor | string | undefined | can take any CSS color (hsl, rgb, hex, ...) |
partCColor | string | undefined | can take any CSS color (hsl, rgb, hex, ...) |
totalColor | string | undefined | can take any CSS color (hsl, rgb, hex, ...) |
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 isslategray
--bg-square
: color for partB squares, the fallback iscadetblue
--bg-square-valued
: color for partA squares, the fallback ispalevioletred
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:
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.