✨ Tailwind Plugin Realtime Colors

This plugin allows you to load colors from URL of Realtime Colors.

❄️ Installation

First install the package using a package manager of your choice.

# using npm
npm install tailwind-plugin-realtime-colors
# or pnpm
pnpm install tailwind-plugin-realtime-colors
# or bun
bun add tailwind-plugin-realtime-colors

If you haven't setup Tailwind CSS yet, you can follow the official guide.

Now go to Realtime Colors and choose your colors and copy the URL.

Now add the plugin to your tailwind.config.js file.

// tailwind.config.js

// Using ESM Syntax
import realtimeColors from "tailwind-plugin-realtime-colors";
export default {
  // ...
  plugins: [realtimeColors("https://www.realtimecolors.com/?colors=...")],
  // ...
};

// Using CommonJS Modules
const realtimeColors = require("tailwind-plugin-realtime-colors");
module.exports = {
  // ...
  plugins: [realtimeColors("https://www.realtimecolors.com/?colors=...")],
  // ...
};

Paste the your url as the argument for the plugin.

Now you can use the colors in your CSS.

<div class="bg-primary-500 text-text hover:bg-secondary-400/90">
  Hello World
</div>

🛠️ Configuration

You can configure the plugin by either passing an url and a optional config object or by passing a config object with colors.

realtimeColors("https://www.realtimecolors.com/?colors=...", {
  theme: true,
});

// or pass a config object with colors
realtimeColors({
  colors: {
    text: "#ededee",
    background: "#0c0d13",
    primary: "#9aa5d1",
    secondary: "#243579",
    accent: "#3053dc",
  },
  theme: true,
});

🔎 Options

| Option | Type | Default | Description | | ---------------- | ---------- | ------------------------------------ | -------------------------------------------------------------------------------------------- | | colors | object | {} | The colors to use. If you pass an url, this will be ignored. | | theme | boolean | true | Whether to generate invert variant and use them with css variables. | | shades | string[] | ["primary", "secondary", "accent"] | The colors to generate shades of | | prefix | string | "" | The prefix to use for the colors. | | shadeAlgorithm | string | "tailwind" | The algorithm to use for generating shades. See Shading Algorithms | | colorFormat | string | "rgb" | The format to use for the colors. Can be rgb, hsl, lch, lab |

🎨 Shading Algorithms

| Algorithm | Description | Notes | | ---------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | tailwind | Uses a Tint and Shade based approach like TailwindCSS. | Generates better results. This is the default. | | realtimeColors | Uses the same algorithm like Realtime Colors. | Shades are not that great. You can use this if you want feature parity with Realtime Colors. |

🔥 Dynamic Colors

This doesn't work with URL based colors.

Sometimes you may want to use dynamic colors based on user preferences. To skip generating a color at build time, you can pass dynamic() as the color value.

realtimeColors({
  colors: {
    text: "#ededee",
    background: "#0c0d13",
    primary: "dynamic()",
    secondary: "#243579",
    accent: "#3053dc",
  },
  theme: true,
});

This will skip generating the primary color in the CSS. You will need to manually set the primary color using CSS variables. To help in generating the CSS, you can use the new helper functions exported along with the plugin.

import { generateDynamicPalette, invertColor } from "tailwind-plugin-realtime-colors";

const primaryColor = getPrimaryColorSomehow();

// You can also pass a config object as the second argument
const palette = generateDynamicPalette({primary: primaryColor});
const darkPalette = generateDynamicPalette(invertColor({primary: primaryColor}));

// Now you can use the styles in your CSS
for (const [key, value] of Object.entries(palette)) {
  document.documentElement.style.setProperty(key, value);
}
// Use dark palette for dark mode later

🏗️ How to contribute

🐛 Reporting Bugs

If you encounter any bugs, please report them in the Issues.

🎋 Adding new features

You need to first fork this repository and then clone it to your local machine.

git clone https://github.com/<your-username>/tailwind-plugin-realtime-colors
cd tailwind-plugin-realtime-colors

Now you need to create a new branch for your changes. For features, you may want to use feat/<feature-name> as the branch name.

git checkout -b feat/<feature-name>

Now you can make your changes. After you are done, you need to commit your changes.

git add .
git commit -m "feat: ✨ My Awesome feature"

We follow Conventional Commits for commit messages.

Now you need to push the changes to your forked repository.

git push origin feat/<feature-name>

Now you need to create a Pull Request to the original repository. And you are done!

We will review your changes and merge them if everything looks good.

💸 Sponsorship

If you find this plugin useful, please consider sponsoring me. This will help me spend more time on these projects.

📜 License

This project is licensed under the MIT License.