Theming

Customize MattersUI to match your brand and create beautiful, consistent user interfaces.

Theme Provider

MattersUI comes with a built-in ThemeProvider component that enables light and dark mode support.

Basic Setup

Wrap your application with the ThemeProvider:

jsx

import React from 'react';
import { ThemeProvider } from 'mattersui';

function App() {
  return (
    <ThemeProvider defaultMode="light">
      <YourApp />
    </ThemeProvider>
  );
}

Using the Theme Hook

Access and modify the current theme using the useTheme hook:

jsx

import React from 'react';
import { useTheme, Button } from 'mattersui';

function ThemeToggle() {
  const { mode, setMode, toggleMode } = useTheme();
  
  return (
    <div>
      <p>Current theme: {mode}</p>
      <Button onClick={toggleMode}>
        Toggle Theme
      </Button>
      <Button onClick={() => setMode('light')}>
        Light Mode
      </Button>
      <Button onClick={() => setMode('dark')}>
        Dark Mode
      </Button>
    </div>
  );
}

Color Customization

MattersUI uses Tailwind CSS for styling. You can customize colors by extending your Tailwind configuration.

Customizing Colors

Extend your tailwind.config.js file to customize the color palette:

// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{js,jsx,ts,tsx}',
    // Include MattersUI components
    './node_modules/mattersui/**/*.js',
  ],
  theme: {
    extend: {
      colors: {
        // Customize primary color
        primary: {
          50: '#f0f9ff',
          100: '#e0f2fe',
          200: '#bae6fd',
          300: '#7dd3fc',
          400: '#38bdf8',
          500: '#0ea5e9',
          600: '#0284c7',
          700: '#0369a1',
          800: '#075985',
          900: '#0c4a6e',
        },
        // Customize secondary color
        secondary: {
          50: '#f5f3ff',
          100: '#ede9fe',
          200: '#ddd6fe',
          300: '#c4b5fd',
          400: '#a78bfa',
          500: '#8b5cf6',
          600: '#7c3aed',
          700: '#6d28d9',
          800: '#5b21b6',
          900: '#4c1d95',
        },
        // Add other custom colors as needed
      },
    },
  },
  plugins: [],
}

MattersUI components will automatically use these customized colors.

Dark Mode

MattersUI supports dark mode out of the box. The ThemeProvider handles theme switching and persistence.

Dark Mode Configuration

By default, MattersUI detects the user's system preference for dark/light mode. You can override this with the defaultMode prop:

jsx

<ThemeProvider defaultMode="dark">
  {/* Your app */}
</ThemeProvider>

Custom Dark Mode Classes

For custom components, use Tailwind's dark mode variant:

jsx

<div className="bg-white text-black dark:bg-slate-900 dark:text-white">
  This div adapts to the current theme
</div>

Component Styling

Most MattersUI components accept a className prop for custom styling.

Custom Component Styling

jsx

import { Button } from 'mattersui';

// Apply custom styles
<Button 
  variant="primary" 
  className="px-8 py-3 rounded-full shadow-lg"
>
  Custom Styled Button
</Button>

Your custom classes will be merged with MattersUI's default styles.

Advanced Theming

For more advanced theming needs, you can extend the MattersUI theme system.

Custom Theme Variables

Add custom CSS variables to your global stylesheet:

css

:root {
  --mui-border-radius: 0.375rem;
  --mui-font-sans: 'Inter', sans-serif;
  --mui-transition-duration: 150ms;
}

.dark {
  --mui-border-radius: 0.5rem;
}

Then use these variables in your Tailwind configuration:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      borderRadius: {
        DEFAULT: 'var(--mui-border-radius)',
      },
      fontFamily: {
        sans: ['var(--mui-font-sans)'],
      },
      transitionDuration: {
        DEFAULT: 'var(--mui-transition-duration)',
      },
    },
  },
}