chartjs-plugin-tailwindcss-colors

chartjs-plugin-tailwindcss-colors

This project is still under development

Colorize your Chart.js components using TailwindCSS!

This plugin integrates your existing TailwindCSS colors configuration so you can continue to use it on your Chart.js components, without the hassle.

Getting started

Installation

Package:

pnpm add chartjs-plugin-tailwindcss-colors # or npm install

CDN:

<script src="https://cdn.jsdelivr.net/npm/chart.js@<version>/dist/chart.umd.min.js"></script>
<script src="https://cdn.tailwindcss.com"></script>

<!-- UMD -->
<script src="https://cdn.jsdelivr.net/npm/chartjs-plugin-tailwindcss-colors@<version>/dist/plugin.umd.min.js"></script>
<script>
  Chart.register(twColorsPlugin(tailwind.config))
</script>

<!-- or as an ESM -->
<script type="module">
  import twColorsPlugin from "https://cdn.jsdelivr.net/npm/chartjs-plugin-tailwindcss-colors@<version>/+esm"
</script>

Integration

Simply include the plugin inside the plugins options in your Chart.js instance's config, provide your TailwindCSS config, and give it some color options:

import twColorsPlugin from "chartjs-plugin-tailwindcss-colors"
import twConfig from "./tailwind.config"

const config = {
  data: {
    datasets: [
      {
        data: [...],
        borderColor: "yellow-500",
        backgroundColor: "yellow-500/50", // or #eab308/50
      },
    ],
  },
  plugins: [twColorsPlugin(twConfig)],
}

// ...
const chart = new Chart(ctx, config)

And that's about it, you're good to go!

NOTE: Only tested with vanilla JS and react-chartjs-2 using chart.js@3 as of initial release. If you encounter problems with other frameworks and versions of Chart.js, please feel free to submit to the issue tracker!

Parsable Chart Options

In addition to the above, it can also parse the following color options:

• color
• hoverBorderColor
• hoverBackgroundColor
• pointBorderColor
• pointBackgroundColor
• pointHoverBackgroundColor
• pointHoverBorderColor
• fill.above
• fill.below

Global Defaults

To set the global colors, you can register it and add defaults:

Chart.register(twColorsPlugin(tailwindConfig))

Chart.defaults.borderColor = "yellow-500"
Chart.defaults.backgroundColor = "yellow-500/50" // or #eab308/50

Now if a chart's parsable option is not configured, it will fallback to the values provided above.

NOTE: Since this plugin is still on its initial release, there might be other overlooked color options left to be parsed (also, bugs). As such, feedback is highly encouraged!

Invalid Color Handling

By default, the plugin warns when it encounters an invalid color such as red-500d. To change this behavior, pass an options object as the third argument:

const plugin = twColorsPlugin(
  twConfig,
  {},
  {
    invalidColorHandling: "warn", // or "throw" / "ignore"
  },
)

• "warn" (default): Leaves invalid colors as-is and continues converting valid colors. Each invalid color produces one warning per chart, including across updates.
• "throw": Throws an error when an invalid color is found. If it is in a color array, none of the converted colors from that array are applied to the chart.
• "ignore": Leaves invalid colors as-is and continues converting valid colors, without warnings.

For example, with backgroundColor: ["red-500", "red-500d"], "warn" and "ignore" apply ["#ef4444", "red-500d"] to backgroundColor. With "throw", the plugin throws an error and leaves backgroundColor as ["red-500", "red-500d"].

Warnings and errors include the color option's path and the array or data index when applicable.

Native CSS colors are passed through unchanged. Whether they render correctly depends on Chart.js and your browser.

Why did I even make this?

I absolutely love how fast I can prototype things with TailwindCSS. However, keeping my Chart.js component's colors consistent with my TailwindCSS config has been pretty much a hassle, to say the least. While you can just use TailwindCSS's resolveConfig helper function, it is far more intuitive and convenient to just use TailwindCSS color classes directly rather than something like fullConfig.theme.colors.red[500]. What's more, it doesn't even handle opacity, which is something I use all the time.

That's why this plugin was made in order to seamlessly blend Chart.js's color options with my TailwindCSS workflow. Now I'm sharing this with all of you!

Contributing

For making feature requests and other related information, please refer to the contributing guidelines. This project is tested with BrowserStack.

License

chartjs-plugin-tailwindcss-colors is available under the MIT license.