Getting Started

Reablocks theming is seamlessly integrated into the Tailwind CSS configuration, allowing for a highly customizable design system. This approach leverages Tailwind's utility-first CSS to offer you an extensive range of design tokens such as colors, border radii, shadows, and font sizes. In addition, Reablocks provides a set of pre-defined Storybook blocks that can be used to quickly build and customize your UI components in a Storybook environment.

Integrating Reablocks Theme in Your Application

To get started with Reablocks theming, you first need to incorporate the ThemeProvider into the root of your application. This provider applies the selected theme across all your components, ensuring a consistent look and feel.

Basic Theme Example

import { ThemeProvider, theme } from 'reablocks';
 
export const App = () => (
  <ThemeProvider theme={theme}>
    <YourComponents />
  </ThemeProvider>
);

Result: In this example, the darkTheme from Reablocks is applied to your application. Simply wrap your component hierarchy with the ThemeProvider, and the theme is automatically applied.

Extending the Reablocks Theme

Reablocks allows you to extend its themes to customize according to your design requirements. You can modify existing styles or add new ones to fit your application's unique design language.

Customizing Theme Example

import { ThemeProvider, theme, extendTheme, PartialReablocksTheme } from 'reablocks';
 
const customTheme: PartialReablocksTheme = {
  components: {
    button: {
      base: 'bg-lime-600 text-gray-300',
      variants: {
        filled: 'bg-lime-600 hover:bg-lime-700',
        outline: 'bg-transparent border-lime-600 border',
        text: 'bg-transparent border-0'
      },
      sizes: {
        small: 'p-2',
        medium: 'p-3',
        large: 'p-4'
      }
    }
  }
};

You can extend the colors, variants, and sizes of applicable components with any custom values. This allows you to create properties that are specific to your app's design system.

const customTheme: PartialReablocksTheme = {
  components: {
    button: {
      base: 'bg-lime-600 text-gray-300',
      variants: {
        ...
        destructive: 'bg-red-600 hover:bg-red-700',
      },
      sizes: {
        ...
        xxl: 'p-6',
      }
    }
  }
};

By using the extendTheme function, you can merge your customizations with the base theme, resulting in a coherent design system that still benefits from Reablocks' foundation.

export const App = () => (
  <ThemeProvider theme={extendTheme(theme, customTheme)}>
    <YourComponents />
  </ThemeProvider>
);

Result: This example demonstrates how to create a customTheme that extends the darkTheme.

Switching themes

Simply switch the class or the data-theme attribute on the html element to change the theme.

<html class='dark'> // or class='light'
  ...
</html>

Defining Custom Tokens with TailwindCSS

Reablocks themes can further leverage TailwindCSS's configuration to define custom design tokens. This allows for an even deeper level of customization, integrating seamlessly with your TailwindCSS setup.

TailwindCSS Configuration Example

import { type Config } from 'tailwindcss';
import colors from 'tailwindcss/colors';
 
const config: Config = {
  content: [
    './src/**/*.{js,jsx,ts,tsx}',
    'node_modules/reablocks/**/*.js'
  ],
  theme: {
    extend: {
      colors: {
        primary: {
          50: '#f3f4f6',
          100: '#e7e9ed',
          200: '#c3c8d3',
          300: '#9fa6b9',
          400: '#565f86',
          500: '#0d1733',
          600: '#0c1530',
          700: '#0a1228',
          800: '#080f20',
          900: '#060c19',
        },
        secondary: colors.slate,
      }
    },
  },
};
 
export default config;

Result: In this configuration, we extend the default TailwindCSS theme to include custom colors for primary and secondary palettes. The extend property allows you to add to the existing design tokens without overriding them, ensuring you can update and maintain your theme easily.

Creating a reusable component with a custom theme

You can also pass a theme directly to any component as a prop. This will override the theme for that component, but not its children. This is useful if you want to create a reusable component with a theme that differs from the global theme.

import { tooltipTheme, TooltipTheme, extendComponentTheme } from 'reablocks';
 
const customTheme = extendComponentTheme<TooltipTheme>(tooltipTheme, {
  base: 'rounded bg-green-800 text-white font-bold p-3 text-base'
});
 
export const CustomTooltip = () => (
  <Tooltip theme={customTheme} content="Hi there">Hover me</Tooltip>
);

Migration API