Theme

Pol-ui offers powerful theming capabilities that allow you to customize the look and feel of your application.

Let's have a look at the different layers of customization:

1 - General configuration - Tailwind CSS

The main point to style Pol-ui is to use Tailwind CSS. It is a utility-first CSS framework that allows you to build custom designs without ever leaving your HTML. The file called tailwind.config.js is the main configuration file for Tailwind CSS. It allows you to customize the default theme, add new utilities, and more.

Tailwind Plugin

To add facilities to the Tailwind CSS configuration, you can use the tailwindcss plugin that we provide inside of the package, there is no need to install anything else.

// tailwind.config.ts
import type { Config } from "tailwindcss";
import typography from "@tailwindcss/typography";
import { poluiPlugin } from "pol-ui";
 
export default {
  content: [
    "./src/**/*.tsx",
    "./node_modules/pol-ui/**/*.js",
  ],
  darkMode: ["class"],
  plugins: [typography, poluiPlugin({})],
} satisfies Config;

This plugin provides default color configuration for free, but you can customize it as you wish.

Customize the plugin configuration

You can customize the plugin configuration by passing an object to the poluiPlugin function. This object has the following properties:

type CustomPluginConfig = {
  colors?: SomeColors;
  prefix?: string;
};
export type ColorScale = Partial<{
  50: string;
  100: string;
  200: string;
  300: string;
  400: string;
  500: string;
  600: string;
  700: string;
  800: string;
  900: string;
}>;
 
export type ThemeColors = {
  primary: ColorScale;
  secondary: ColorScale;
  success: ColorScale;
  warning: ColorScale;
  error: ColorScale;
  info: ColorScale;
};
 
export type SomeColors = Partial<ThemeColors>;

colors

You can provide any color you want to customize the default theme. The SomeColors type is a partial of the ThemeColors type, so you can provide only the colors you want to customize. There is no need then to provide all the colors.

prefix

You can provide a prefix to the colors that will be generated by the plugin. This is useful when you want to use the same color scale for different components.

Example of a custom configuration

import type { Config } from "tailwindcss";
import typography from "@tailwindcss/typography";
import { poluiPlugin } from "pol-ui";
 
export default {
  content: [
    "./app/**/*.{ts,tsx}",
    "./components/**/*.{ts,tsx}",
    "./content/**/*.mdx",
    "./node_modules/pol-ui/**/*.js",
  ],
  darkMode: ["class"],
 
  plugins: [
    typography,
    poluiPlugin({
      colors: {
        secondary: {
          500: "#FFD700",
        },
      },
    }),
  ],
} satisfies Config;

This configuration will override the default secondary color with a golden color, you can provide any shadow from any color.

Default colors

Inside of the plugin, you can customize our used colors:

• primary
• secondary
• success
• warning
• error
• info

Adding more colors

In case you want to add more colors to the theme, you can use the extend property of the theme object in the tailwind.config.js file.

// tailwind.config.js
import { type Config } from "tailwindcss";
 
  export default {
  theme: {
    extend: {
      colors: {
        "my-custom-color": "#FFD700",
      },
    },
  },
} satisfies Config;

This new color called my-custom-color will be available to use in your application, Pol-ui won't use it, but you can use it in the rest of your application as normal tailwind colors.

The good part of using the plugin is that for free you will have the colors detailed before without the need to add them manually.

If you don't want to use the plugin

2 - General configuration - Theming

In the root of you application, you can wrap your app with a component called ProviderProps , where a prop called theme is optionally sent. This prop is a object that has the same structure of the Theme type.

interface ThemeProps {
  mode?: ThemeMode;
  theme?: CustomPoluiTheme;
}

Theme mode

You can specify the default light or mode for your application, the default value is auto. This means that the application will use the system preference to choose the mode. You can send light or dark as well to force the mode.

Theme object provided

The theme object is a quite interesting prop that allows you to modify each single tailwind class created in Pol-ui in your whole application.

export interface PoluiTheme {
  accordion: AccordionTheme;
  alert: AlertTheme;
  avatar: AvatarTheme;
  badge: BadgeTheme;
  popover: PopoverTheme;
  banner: BannerTheme;
  breadcrumb: BreadcrumbTheme;
  button: ButtonTheme;
  // ... and so on
}

Each single component has a prop called theme that is a structured object used to apply tailwind styles to the component.

If you for example, modify the global alert theme here, all your alerts will have this same changes.

 
 
const AppProvider = ({ children }: PropsWithChildren) => {
  return (
      <PoluiProvider theme={
        theme:{
          alert: {
              base: "bg-red-500 text-white",
          },
        }
      }>{children}</PoluiProvider>
  );
};

Using this configuration, all alerts will have a red background and white text.

3 - Component customization

As well as the global theme, you can customize each single component in your application.

Using Tailind CSS classes

All components have a prop called className that allows you to apply tailwind classes to the component.

<Alert className="bg-red-500 text-white">This is a custom alert</Alert>

This will have the same effect as applying tailwind classes to any HTML element.

Using the theme prop

Some components have a complex structure inside and it's not that easy as applying a class to a div.

To solve this problem some components provides different tailwind props for that as inputClassName, iconClassName, buttonClassName and so on.

To be sure that you can change each single Tailwind class, you can use the same theme prop that we saw before but specific to the component.

<Alert theme={{ base: "bg-red-500 text-white" }}>This is a custom alert</Alert>

This will apply the same changes as the previous example, but only for this single alert.