Theme

Customizing the default theme for your project.

The theme section of your windi.config.js or windi.config.ts file is where you define your project’s color palette, type scale, fonts, breakpoints, border radius values, and more.

windi.config.js

import { defineConfig } from "windijs";

export default defineConfig({
  screens: {
    sm: "480px",
    md: "768px",
    lg: "976px",
    xl: "1440px",
  },
  colors: {
    blue: "#1fb6ff",
    purple: "#7e5bef",
    pink: "#ff49db",
    orange: "#ff7849",
    green: "#13ce66",
    yellow: "#ffc82c",
    grayDark: "#273444",
    gray: "#8492a6",
    grayLight: "#d3dce6",
  },
  fontFamily: {
    sans: ["Graphik", "sans-serif"],
    serif: ["Merriweather", "serif"],
  },
  extend: {
    spacing: {
      128: "32rem",
      144: "36rem",
    },
    borderRadius: {
      xl: {
        4: "2rem",
      },
    },
  },
});

Theme structure

The theme object contains keys for screens, colors, and spacing, as well as a key for each customizable utilities.

See the theme configuration reference or the default theme config for a complete list of theme options.

TIP

If you have experience with windicss/tailwindcss, you should pay attention to the differences, the way how configuration works in windijs is completely different, for more info please refer to this post.

Screens

The screens key allows you to customize the responsive breakpoints in your project.

windi.config.js

import { defineConfig } from "windijs";

export default defineConfig({
  theme: {
    screens: {
      sm: "640px", // => @media (min-width: 640px) { ... }
      md: "768px", // => @media (min-width: 768px) { ... }
      lg: "1024px", // => @media (min-width: 1024px) { ... }
      xl: "1280px", // => @media (min-width: 1280px) { ... }
      xxl: "1536px", // => @media (min-width: 1536px) { ... }
    },
  },
});

Overriding a single screen

To override a single screen size (like lg), add your custom screens value under the theme.extend key:

windi.config.js

import { defineConfig } from "windijs";

export default defineConfig({
  theme: {
    extend: {
      screens: {
        lg: "992px", // => @media (min-width: 992px) { ... }
      },
    },
  },
});

Adding new breakpoints

You can also use the extend key to add new breakpoints.

windi.config.js

import { defineConfig } from "windijs";

export default defineConfig({
  theme: {
    extend: {
      screens: {
        tiny: "345px", // => @media (min-width: 345px) { ... }
        big: "1600px", // => @media (min-width: 1600px) { ... }
      },
    },
  },
});

Custom media queries

By default, Windi JS will use mobile first mode, which means generating media query like @media (min-width: ...).

If you want to use a custom media query, such as desktop first mode, it's very easy, you need to use the variants key to achieve it. The new variants we define with the variants key will replace the previous variants generated by theme.screens.

windi.config.js

import { defineConfig } from "windijs";

export default defineConfig({
  variants: {
    xxl: "@media (max-width: 1535px)",
    xl: "@media (max-width: 1279px)",
    lg: "@media (max-width: 1023px)",
    md: "@media (max-width: 767px)",
    sm: "@media (max-width: 639px)",
  },
});

TIP

You must think that we can define a function to do this, Windi JS currently does not provide this helper, but you can easily do it yourself.

import { defineConfig } from "windijs";

const desktopVariants = screens => Object.fromEntries(Object.entries(screens).map(([k, v]) => [k, `@media (max-width: ${v})`]));

export default defineConfig({
  variants: {
    ...desktopVariants({
      xxl: "1535px",
      xl: "1279px",
      lg: "1023px",
      md: "767px",
      sm: "639px",
    }),
  },
});

Or if you want your breakpoints to specify both a min-width and a max-width.

windi.config.js

import { defineConfig } from "windijs";

export default defineConfig({
  variants: {
    sm: "@media (min-width: 640px and max-width: 767px)",
    md: "@media (min-width: 768px and max-width: 1023px)",
    lg: "@media (min-width: 1024px and max-width: 1279px)",
    xl: "@media (min-width: 1280px and max-width: 1535px)",
    xxl: "@media (min-width: 1536px)",
  },
});

Custom variant is a very powerful feature, please refer to the Custom Variant Section for more information.

Colors

The colors key allows you to customize the global color palette for your project.

windi.config.js

import { defineConfig } from "windijs";

export default defineConfig({
  theme: {
    colors: {
      transparent: "transparent",
      black: "#000",
      white: "#fff",
      gray: {
        100: "#f7fafc",
        // ...
        900: "#1a202c",
      },
      // ...
    },
  },
});

By default, these colors used by all color-related utilities, like bg, border, text, and others.

Using custom colors

If you’d like to completely replace the default color palette with your own custom colors, add your colors directly under the theme.colors section of your configuration file:

windi.config.js

import { defineConfig } from "windijs";

export default defineConfig({
  theme: {
    colors: {
      transparent: "transparent",
      current: "currentColor",
      white: "#ffffff",
      purple: "#3f3cbb",
      midnight: "#121063",
      metal: "#565584",
      silver: "#ecebff",
      bubbleGum: "#ff77e9",
      bermuda: "#78dcca",
      tahiti: {
        DEFAULT: "#06b6d4",
        100: "#cffafe",
        200: "#a5f3fc",
        300: "#67e8f9",
        400: "#22d3ee",
        500: "#06b6d4",
        600: "#0891b2",
        700: "#0e7490",
        800: "#155e75",
        900: "#164e63",
      },
      rgbColor: "rgb(22, 22, 22)",
      rgbaColor: "rgba(22, 22, 22, 0.5)",
      hslColor: "hsl(10, 10%, 20%)",
      hwbColor: "hwb(10 10% 20% / 0.2)",
      withVariable: "rgb(var(--color-secondary))",
    },
  },
});

You can also extend the default colors.

windi.config.js

import { defineConfig } from "windijs";

export default defineConfig({
  theme: {
    extend: {
      colors: {
        brown: {
          50: "#fdf8f6",
          100: "#f2e8e5",
          200: "#eaddd7",
          300: "#e0cec7",
          400: "#d2bab0",
          500: "#bfa094",
          600: "#a18072",
          700: "#977669",
          800: "#846358",
          900: "#43302b",
        },
      },
    },
  },
});

Using built-in colors

Windi JS includes a range of popular framework colors, they are from (apple/bootstrap/bulma/material/tailwind/web/windi), you can choose the best for yourself. And also don't forget to say thanks to all these frameworks and their developers.

For example, if you want to use material colors.

windi.config.js

import { baseColors, materialColors, defineConfig } from "windijs";

export default defineConfig({
  theme: {
    colors: {
      ...baseColors, // including inherit, current, transparent, black, white
      ...materialColors, // iOSColor, macOSColors, watchOSColors, bootstrapColors, bulmaColors, tailwindColors, webColors, windiColors
    },
  },
});

You can also combine different colors from variant frameworks.

windi.config.js

import { baseColors, bootstrapPink, bulmaRed, materialOrange, tailwindCyan, windiDark, windiLight, defineConfig } from "windijs";

export default defineConfig({
  theme: {
    colors: {
      ...baseColors,
      pink: bootstrapPink,
      red: bulmaRed,
      orange: materialOrange,
      green: webGreen,
      cyan: tailwindCyan,
      dark: windiDark,
      light: windiLight,
    },
  },
});

All built-in colors defined in the package @windijs/colors package. Please refer to the colors API documentation for more details.

Generating colors

Windi JS has very powerful color processing helpers built in, which allowing you to quickly generate your own color patterns, convert bright colors to dark colors, and other colors processing methods.

import { Color, getDarkColor, getLightColor } from "windijs";

const red = new Color("#ff0000");
red.lightenSet(5).map(i => i.hex); // ["#f00", "#f33", "#f66", "#f99", "#fcc"]
red.darkenSet(5).map(i => i.hex); // ["#f00", "#c00", "#900", "#600", "#300"]

getLightColor(Color.hex("#485fc7")).hex; // "#eff1fa"
getDarkColor(Color.hex("#485fc7")).hex; // "#384fb8"

Color.hex("#c69").saturate(20).hex; // "#e05299"
Color.hex("#d2e1dd").scale({ lightness: -10, saturation: 10 }).hex; // "#b1d3ca"

// more...

All built-in helpers defined in the package @windijs/helpers package. Please refer to the helpers API documentation for more details.

Spacing

The spacing key allows you to customize the global spacing and sizing scale for your project.

windi.config.js

import { defineConfig } from "windijs";

export default defineConfig({
    theme: {
        spacing: {
            0: '0',
            1: '0.25rem',
            2: '0.5rem',
            3: '0.75rem',
            3.5: '0.875',
            4': '24px',
            5: '32px',
            6: '48px',
        }
    }
})

By default, these values inherited by the padding, margin, width, height, maxHeight, gap, inset, space, translate utilities...

Other Options

The rest of the theme options used to configure which values are available for each individual utility.

For example, the borderRadius key lets you customize which border radius utilities will generated:

windi.config.js

import { defineConfig } from "windijs";

export default defineConfig({
  theme: {
    borderRadius: {
      none: "0",
      sm: ".125rem",
      DEFAULT: ".25rem",
      lg: ".5rem",
      full: "9999px",
    },
  },
});

The keys determine how you use these utilities, and the values determine the value of the actual CSS declaration.

The example borderRadius configuration can used like this,

[rounded.none, rounded.sm, rounded, rounded.lg, rounded.full];

and they would generate the following CSS classes:

css

/* rounded.none */
.a {
  border-radius: 0;
}
/* rounded.sm */
.b {
  border-radius: 0.125rem;
}
/* rounded */
.c {
  border-radius: 0.25rem;
}
/* rounded.lg */
.d {
  border-radius: 0.5rem;
}
/* rounded.full */
.e {
  border-radius: 9999px;
}

You’ll notice that using a key of DEFAULT in the theme configuration created the class rounded with no suffix. This is a common convention in Windi and supported by all utilities.

To learn more about customizing a specific utility, visit the documentation for that utility.

For a complete reference of available theme properties and their default values, see the default theme configuration.

Theme customzation

Out of the box, your project will use the values from the default theme configuration. If you would like to customize the default theme, you have a few different options depending on your goals.

Extending the default theme

If you’d like to preserve the default values for a theme option but also add new values, add your extensions under the extend key in the theme section of your configuration file.

For example, if you wanted to add an extra breakpoint but preserve the existing ones, you could extend the screens property:

windi.config.js

import { defineConfig } from "windijs";

export default defineConfig({
  theme: {
    extend: {
      screens: {
        big: "1600px",
      },
    },
  },
});

Overriding the default theme

To override an option in the default theme, add your overrides directly under the theme section of your windi.config.js:

windi.config.js

import { defineConfig } from "windijs";

export default defineConfig({
    theme: {
        opacity: {
            0: "0",
            20: "0.2",
            40: "0.4",
            60: "0.6",
            80: "0.8",
            100: "1",
        },
    },
};

This will completely replace Windi's default configuration for that key, so in the example above none of the default opacity utilities would generated.

Any keys you do not provide will inherited from the default theme, so in the above example, the default theme configuration for things like colors, spacing, borderRadius, etc. would preserved.

You can of course both override some parts of the default theme and extend other parts of the default theme within the same configuration:

windi.config.js

import { defineConfig } from "windijs";

export default defineConfig({
    theme: {
        opacity: {
            0: "0",
            20: "0.2",
            40: "0.4",
            60: "0.6",
            80: "0.8",
            100: "1",
        },
        extend: {
            screens: {
                big: '1600px',
            }
        }
    },
};

Referencing other values

If you need to reference another value in your theme, you need to extract them out. Currently, Windi JS does not support theme function, you can check this article to understand why.

For example, you could generate backgroundSize utilities for every value in your spacing scale:

windi.config.js

import { defineConfig } from "windijs";

const spacing = {
    0: '0',
    1: '0.25rem',
    2: '0.5rem',
    3: '0.75rem',
    3.5: '0.875',
    4': '24px',
    5: '32px',
    6: '48px',
}

export default defineConfig({
    theme: {
        spacing,
        backgroundSize: {
            auto: 'auto',
            cover: 'cover',
            contain: 'contain',
            ...spacing
        }
    }
})

Referencing the default theme

If you’d like to reference a value in the default theme for any reason, you can import it directly. Each of the default theme is a separate object, such as borderRadiusConfig, fontFamilyConfig, ...

One example of where this is useful is if you’d like to add a font family to one of Windi’s default font stacks:

windi.config.js

import { defineConfig, fontFamilyConfig } from "windijs";

export default defineConfig({
  theme: {
    extend: {
      fontFamily: {
        sans: ["Lato", ...fontFamilyConfig.sans],
      },
    },
  },
});

Config reference

Except for screens, colors, and spacing, all the keys in the theme object map to one of Windi's utilities. Since many utilities are responsible for CSS properties that only accept a static set of values (like float for example), note that not every plugin has a corresponding key in the theme object.

All these keys are also available under the theme.extend key to enable extending the default theme.

Key	Description
screens	Your project's responsive breakpoints
colors	Your project's color palette
columns	Values for the `columns` property
spacing	Your project's spacing scale
animation	Values for the `animation` property
aspectRatio	Values for the `aspect-ratio` property
backdropBlur	Values for the `backdropBlur` utility
backdropBrightness	Values for the `backdropBrightness` utility
backdropContrast	Values for the `backdropContrast` utility
backdropGrayscale	Values for the `backdropGrayscale` utility
backdropHueRotate	Values for the `backdropHueRotate` utility
backdropInvert	Values for the `backdropInvert` utility
backdropOpacity	Values for the `backdropOpacity` utility
backdropSaturate	Values for the `backdropSaturate` utility
backdropSepia	Values for the `backdropSepia` utility
backgroundColor	Values for the `background-color` property
backgroundImage	Values for the `background-image` property
backgroundOpacity	Values for the `background-opacity` property
backgroundPosition	Values for the `background-position` property
backgroundSize	Values for the `background-size` property
blur	Values for the `blur` utility
brightness	Values for the `brightness` utility
borderColor	Values for the `border-color` property
borderOpacity	Values for the `borderOpacity` utility
borderRadius	Values for the `border-radius` property
borderSpacing	Values for the `border-spacing` property
borderWidth	Values for the `borderWidth` utility
boxShadow	Values for the `box-shadow` property
boxShadowColor	Values for the `boxShadowColor` utility
caretColor	Values for the `caret-color` property
accentColor	Values for the `accent-color` property
contrast	Values for the `contrast` utility
container	Configuration for the `container` utility
content	Values for the `content` property
cursor	Values for the `cursor` property
divideColor	Values for the `divideColor` utility
divideOpacity	Values for the `divideOpacity` utility
divideWidth	Values for the `divideWidth` utility
dropShadow	Values for the `dropShadow` utility
fill	Values for the `fill` utility
grayscale	Values for the `grayscale` utility
hueRotate	Values for the `hueRotate` utility
invert	Values for the `invert` utility
flex	Values for the `flex` property
flexBasis	Values for the `flex-basis` property
flexGrow	Values for the `flex-grow` property
flexShrink	Values for the `flex-shrink` property
fontFamily	Values for the `font-family` property
fontSize	Values for the `font-size` property
fontWeight	Values for the `font-weight` property
gap	Values for the `gap` property
gradientColorStops	Values for the `gradientColorStops` utility
gridAutoColumns	Values for the `grid-auto-columns` property
gridAutoRows	Values for the `grid-auto-rows` property
gridColumn	Values for the `grid-column` property
gridColumnEnd	Values for the `grid-column-end` property
gridColumnStart	Values for the `grid-column-start` property
gridRow	Values for the `grid-row` property
gridRowStart	Values for the `grid-row-start` property
gridRowEnd	Values for the `grid-row-end` property
gridTemplateColumns	Values for the `grid-template-columns` property
gridTemplateRows	Values for the `grid-template-rows` property
height	Values for the `height` property
inset	Values for the `top, right, bottom, and left properties
keyframes Keyframe	values used in the `animation` utility
letterSpacing	Values for the `letter-spacing` property
lineHeight	Values for the `line-height` property
listStyleType	Values for the `list-style-type` property
margin	Values for the `margin` property
maxHeight	Values for the `max-height` property
maxWidth	Values for the `max-width` property
minHeight	Values for the `min-height` property
minWidth	Values for the `min-width` property
objectPosition	Values for the `object-position` property
opacity	Values for the `opacity` property
order	Values for the `order` property
padding	Values for the `padding` property
placeholderColor	Values for the `placeholderColor` utility
placeholderOpacity	Values for the `placeholderOpacity` utility
outlineColor	Values for the `outline-color` property
outlineOffset	Values for the `outline-offset` property
outlineWidth	Values for the `outline-width` property
ringColor	Values for the `ringColor` utility
ringOffsetColor	Values for the `ringOffsetColor` utility
ringOffsetWidth	Values for the `ringOffsetWidth` utility
ringOpacity	Values for the `ringOpacity` utility
ringWidth	Values for the `ringWidth` utility
rotate	Values for the `rotate` utility
saturate	Values for the `saturate` utility
scale	Values for the `scale` utility
sepia	Values for the `sepia` utility
skew	Values for the `skew` utility
space	Values for the `space` utility
stroke	Values for the `stroke` property
strokeWidth	Values for the `stroke-width` property
textColor	Values for the `text-color` property
textDecorationColor	Values for the `text-decoration-color` property
textDecorationThickness	Values for the `text-decoration-thickness` property
textUnderlineOffset	Values for the `text-underline-offset` property
textIndent	Values for the `text-indent` property
textOpacity	Values for the `textOpacity` utility
transformOrigin	Values for the `transform-origin` property
transitionDelay	Values for the `transition-delay` property
transitionDuration	Values for the `transition-duration` property
transitionProperty	Values for the `transition-property` property
transitionTimingFunction	Values for the `transition-timing-function` property
translate	Values for the `translate` utility
width	Values for the `width` property
willChange	Values for the `will-change` property
zIndex	Values for the `z-index` property

All built-in theme configs defined in the package @windijs/config package. Please refer to the config API documentation for more details.

Theme #

Theme structure #

Screens #

Overriding a single screen #

Adding new breakpoints #

Custom media queries #

Colors #

Using custom colors #

Using built-in colors #

Generating colors #

Spacing #

Other Options #

Theme customzation #

Extending the default theme #

Overriding the default theme #

Referencing other values #

Referencing the default theme #

Config reference #

Theme

Theme structure

Screens

Overriding a single screen

Adding new breakpoints

Custom media queries

Colors

Using custom colors

Using built-in colors

Generating colors

Spacing

Other Options

Theme customzation

Extending the default theme

Overriding the default theme

Referencing other values

Referencing the default theme

Config reference