Customizing Theme

Kuma UI provides you with a flexible way to define your theme. The createTheme function can be used to set up theme tokens like colors and breakpoints, as well as to define base and variant styles for your components.

Note that Kuma UI is a headless component library, which means it doesn't come with a default theme. Styles won't be applied to your components unless you define them in your theme.

Defining Your Theme

Here's an example of how you can define your theme:

kuma.config.ts

import { createTheme } from "@kuma-ui/core";
 
const theme = createTheme({
  colors: {
    red: {
      100: "red",
    },
    blue: "blue",
  },
  spacings: {
    sm: "0.5rem",
    md: "1rem",
  },
  breakpoints: {
    sm: "400px",
    md: "700px",
  },
  components: {
    Button: {
      defaultProps: {
        bg: "black", // bg is short for background
        p: "10px", // p is short for padding
      },
    },
  },
});
 
type UserTheme = typeof theme;
 
declare module "@kuma-ui/core" {
  export interface Theme extends UserTheme {}
}
 
export default theme;

In the above example, the theme is defined with a set of colors, spaces, a breakpoint, as well as base styles for the Button component.

If you're using TypeScript, you can benefit from type inference when writing props for your application by extending the Kuma UI Theme interface with your user-defined theme:

type UserTheme = typeof theme;
 
declare module "@kuma-ui/core" {
  export interface Theme extends UserTheme {}
}

Don't forget: To leverage type inference and enable autocompletion of theme tokens and variants in your application, be sure to include kuma.config.ts in the include array of your tsconfig.json.

tsconfig.json

{
  "include": ["./kuma.config.ts"]
}

Using the Theme

Theme Tokens

As of now, the available theme tokens include colors, fonts, fontSizes, fontWeights, lineHeights, letterSpacings, spacings, sizes, radii, and zIndices. Check the Theme Tokens page for a detailed guide on using each token.

Breakpoints

Breakpoints are a separate category, defined as an object with keys being the breakpoint names and values being the CSS width values. These can be utilized in your media queries.

Component Styles

You can define styles for your components in the components section of your theme. Each component can have defaultProps and variants styles:

Default Props: defaultProps are applied to all instances of a component, as configured in your theme configuration. For instance, if you set a variant prop for the Button component in your theme configuration, all Button instances in your app will have that prop by default.
Variant Styles: Variant styles can be applied to a component by passing a variant prop to it. For example, if you have a primary variant for the Button component, you can apply it like so: <Button variant="primary" />.

This allows for a high degree of flexibility and consistency in styling your components across your application.

k Theme Tokens