CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-mui--system

MUI System is a set of CSS utilities to help you build custom designs more efficiently with composable style functions, responsive design utilities, and theme-aware styling.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

theme-system.mddocs/

Theme System

Complete theming system for creating consistent design tokens, providing theme context, and accessing theme values in components. The theme system enables centralized design management and consistent styling across applications.

Capabilities

Theme Creation

Creates complete theme objects with default values and custom configuration options.

/**
 * Generate a theme based on the options received
 * @param options - Takes an incomplete theme object and adds the missing parts
 * @param args - Deep merge the arguments with the about to be returned theme
 * @returns A complete, ready-to-use theme object
 */
function createTheme(options?: ThemeOptions, ...args: object[]): Theme;

interface ThemeOptions {
  /** Shape configuration for border radius */
  shape?: ShapeOptions;
  
  /** Breakpoint system configuration */
  breakpoints?: BreakpointsOptions;
  
  /** Text direction (left-to-right or right-to-left) */
  direction?: Direction;
  
  /** Component mixins and utilities */
  mixins?: Mixins;
  
  /** Color palette configuration */
  palette?: Record<string, any>;
  
  /** Shadow elevation system */
  shadows?: Shadows;
  
  /** Spacing function configuration */
  spacing?: SpacingOptions;
  
  /** Animation and transition configuration */
  transitions?: Transitions;
  
  /** Component default props and style overrides */
  components?: Record<string, any>;
  
  /** Typography system configuration */
  typography?: Typography;
  
  /** Z-index layering system */
  zIndex?: ZIndex;
  
  /** sx prop configuration (advanced) */
  unstable_sxConfig?: SxConfig;
}

interface Theme extends CssContainerQueries {
  /** Shape configuration (border radius) */
  shape: Shape;
  
  /** Breakpoint system with helper methods */
  breakpoints: Breakpoints;
  
  /** Text direction */
  direction: Direction;
  
  /** Color palette with mode support */
  palette: Record<string, any> & { mode: 'light' | 'dark' };
  
  /** Shadow elevation values */
  shadows?: Shadows;
  
  /** Spacing transformation function */
  spacing: Spacing;
  
  /** Animation and transition configuration */
  transitions?: Transitions;
  
  /** Component default props and overrides */
  components?: Record<string, any>;
  
  /** Component mixins and utilities */
  mixins?: Mixins;
  
  /** Typography system */
  typography?: Typography;
  
  /** Z-index layering values */
  zIndex?: ZIndex;
  
  /** Apply styles conditionally based on color scheme */
  applyStyles: ApplyStyles<'light' | 'dark'>;
  
  /** sx prop configuration */
  unstable_sxConfig: SxConfig;
  
  /** sx prop processor function */
  unstable_sx: (props: SxProps<Theme>) => CSSObject;
}

type Direction = 'ltr' | 'rtl';

// Empty interfaces for module augmentation
interface Typography {}
interface Mixins {}
interface Shadows {}
interface Transitions {}
interface ZIndex {}

Usage Examples:

import { createTheme } from "@mui/system";

// Basic theme
const theme = createTheme();

// Custom theme with palette
const customTheme = createTheme({
  palette: {
    primary: {
      main: '#1976d2',
      light: '#42a5f5',
      dark: '#1565c0',
    },
    secondary: {
      main: '#dc004e',
    },
    mode: 'light',
  },
  spacing: 8,
  shape: {
    borderRadius: 4,
  },
});

// Dark theme
const darkTheme = createTheme({
  palette: {
    mode: 'dark',
    primary: {
      main: '#90caf9',
    },
    background: {
      default: '#121212',
      paper: '#1e1e1e',
    },
  },
});

// Theme with breakpoints
const responsiveTheme = createTheme({
  breakpoints: {
    values: {
      xs: 0,
      sm: 600,
      md: 900,
      lg: 1200,
      xl: 1536,
    },
  },
});

Theme Provider

Provides theme context to child components through React Context API.

/**
 * Theme context provider component
 * @param props - ThemeProvider props
 * @returns Provider component
 */
declare const ThemeProvider: React.ComponentType<ThemeProviderProps>;

interface ThemeProviderProps<Theme = Theme> {
  /** Child components that will receive theme context */
  children: React.ReactNode;
  
  /** Theme object to provide */
  theme: Theme | ((outerTheme: Theme) => Theme);
  
  /** Optional theme identifier for multiple theme contexts */
  themeId?: string;
}

Usage Examples:

import { ThemeProvider, createTheme } from "@mui/system";

const theme = createTheme({
  palette: {
    primary: { main: '#1976d2' },
  },
});

function App() {
  return (
    <ThemeProvider theme={theme}>
      <div>
        {/* All child components have access to theme */}
        <MyComponent />
      </div>
    </ThemeProvider>
  );
}

// Function theme (access to outer theme)
<ThemeProvider theme={(outerTheme) => ({
  ...outerTheme,
  palette: {
    ...outerTheme.palette,
    primary: { main: '#ff5722' },
  },
})}>
  <MyComponent />
</ThemeProvider>

Theme Hooks

React hooks for accessing and using theme values in components.

/**
 * Hook to access the current theme
 * @param defaultTheme - Default theme if no theme provider exists
 * @returns Current theme object
 */
function useTheme<T = Theme>(defaultTheme?: T): T;

/**
 * Hook to access theme without default fallback
 * @returns Current theme object or undefined
 */
function useThemeWithoutDefault<T = Theme>(): T | undefined;

/**
 * Hook to merge component props with theme defaults
 * @param params - Props merging parameters
 * @returns Merged props with theme defaults
 */
function useThemeProps<Theme, Props, Name extends string>(params: {
  props: Props;
  name: Name;
  defaultTheme?: Theme;
  themeId?: string;
}): Props & ThemedProps<Theme, Name>;

/**
 * Utility function to get theme props (non-hook version)
 * @param params - Props merging parameters
 * @returns Merged props with theme defaults
 */
function getThemeProps<Theme, Props, Name extends string>(params: {
  props: Props;
  name: Name;
  theme: Theme;
}): Props & ThemedProps<Theme, Name>;

type ThemedProps<Theme, Name extends string> = {
  [K in keyof Theme]: Theme[K];
};

Usage Examples:

import { useTheme, useThemeProps } from "@mui/system";

// Access theme in component
function MyComponent() {
  const theme = useTheme();
  
  return (
    <div style={{
      backgroundColor: theme.palette.primary.main,
      padding: theme.spacing(2),
      borderRadius: theme.shape.borderRadius,
    }}>
      Themed component
    </div>
  );
}

// Custom hook with theme
function useCustomStyles() {
  const theme = useTheme();
  
  return {
    container: {
      padding: theme.spacing(2),
      [theme.breakpoints.up('md')]: {
        padding: theme.spacing(3),
      },
    },
  };
}

// Component with theme props
function ThemedButton(inProps) {
  const props = useThemeProps({
    props: inProps,
    name: 'MyButton',
  });
  
  const { children, ...other } = props;
  
  return <button {...other}>{children}</button>;
}

Breakpoints System

Responsive breakpoint system with helper methods for media queries and responsive values.

/**
 * Create breakpoints system with helper methods
 * @param options - Breakpoint configuration options
 * @returns Breakpoints object with helper methods
 */
function createBreakpoints(options?: BreakpointsOptions): Breakpoints;

interface BreakpointsOptions {
  /** Breakpoint values in pixels */
  values?: BreakpointValues;
  
  /** CSS unit for breakpoints (default: 'px') */
  unit?: string;
  
  /** Step increment for between() method (default: 5) */
  step?: number;
}

interface BreakpointValues {
  xs: number;
  sm: number;
  md: number;
  lg: number;
  xl: number;
  [key: string]: number;
}

interface Breakpoints {
  /** Breakpoint keys array */
  keys: Breakpoint[];
  
  /** Breakpoint values object */
  values: BreakpointValues;
  
  /** CSS unit used for breakpoints */
  unit: string;
  
  /** Step increment for between() method */
  step: number;
  
  /** Generate min-width media query */
  up(key: Breakpoint | number): string;
  
  /** Generate max-width media query */
  down(key: Breakpoint | number): string;
  
  /** Generate media query between two breakpoints */
  between(start: Breakpoint | number, end: Breakpoint | number): string;
  
  /** Generate media query for specific breakpoint only */
  only(key: Breakpoint): string;
  
  /** Generate media query excluding specific breakpoint */
  not(key: Breakpoint): string;
}

type Breakpoint = 'xs' | 'sm' | 'md' | 'lg' | 'xl';

// Re-exported from breakpoints module
export {
  Breakpoint,
  Breakpoints,
  BreakpointOverrides, // Module augmentation interface
};

Usage Examples:

import { createBreakpoints } from "@mui/system";

// Default breakpoints
const breakpoints = createBreakpoints();

// Custom breakpoints
const customBreakpoints = createBreakpoints({
  values: {
    xs: 0,
    sm: 576,
    md: 768,
    lg: 992,
    xl: 1200,
    xxl: 1400,
  },
});

// Using breakpoint helpers
const styles = {
  container: {
    width: '100%',
    [breakpoints.up('sm')]: {
      maxWidth: '540px',
    },
    [breakpoints.up('md')]: {
      maxWidth: '720px',
    },
    [breakpoints.between('md', 'xl')]: {
      padding: '0 16px',
    },
  },
};

Spacing System

Configurable spacing system for consistent spacing values throughout the application.

/**
 * Create spacing transformation function
 * @param spacingInput - Spacing configuration
 * @returns Spacing function
 */
function createSpacing(spacingInput?: SpacingOptions): Spacing;

type SpacingOptions = 
  | number 
  | number[] 
  | ((factor: number) => number | string)
  | { unit?: string; factor?: number };

/**
 * Spacing transformation function
 * @param value - Spacing value(s) to transform
 * @returns CSS spacing value(s)
 */
interface Spacing {
  (value: number): string;
  (value1: number, value2: number): string;
  (value1: number, value2: number, value3: number): string;
  (value1: number, value2: number, value3: number, value4: number): string;
  (...values: number[]): string;
}

Usage Examples:

import { createSpacing } from "@mui/system";

// Default spacing (8px base)
const spacing = createSpacing();
spacing(1); // '8px'
spacing(2); // '16px'
spacing(1, 2); // '8px 16px'

// Custom spacing unit
const customSpacing = createSpacing(4);
customSpacing(1); // '4px'
customSpacing(2); // '8px'

// Array-based spacing
const arraySpacing = createSpacing([0, 4, 8, 16, 32]);
arraySpacing(1); // '4px'
arraySpacing(4); // '32px'

// Function-based spacing
const funcSpacing = createSpacing((factor) => `${factor * 0.5}rem`);
funcSpacing(2); // '1rem'

Shape System

Shape configuration for consistent border radius values.

/**
 * Default shape configuration
 */
const shape: Shape;

interface Shape {
  /** Default border radius value */
  borderRadius: number;
}

interface ShapeOptions {
  /** Border radius configuration */
  borderRadius?: number;
}

Usage Examples:

import { createTheme } from "@mui/system";

// Theme with custom shape
const theme = createTheme({
  shape: {
    borderRadius: 8,
  },
});

// Using shape in styles
const styles = {
  card: {
    borderRadius: theme.shape.borderRadius,
  },
};

Color Scheme Support

Conditional styling based on light/dark color schemes.

/**
 * Apply styles conditionally based on color scheme
 * @param colorScheme - Target color scheme
 * @returns Style application function
 */
type ApplyStyles<ColorScheme extends string> = (
  colorScheme: ColorScheme
) => (styles: CSSObject) => CSSObject;

Usage Examples:

import { createTheme } from "@mui/system";

const theme = createTheme({
  palette: {
    mode: 'light',
  },
});

// Conditional styles based on color scheme
const styles = {
  paper: {
    backgroundColor: '#fff',
    ...theme.applyStyles('dark', {
      backgroundColor: '#1e1e1e',
    }),
  },
};

Default Props Provider

Provider for setting default props for components without theme integration.

/**
 * Provider for default component props
 * @param props - Provider props
 * @returns Provider component
 */
declare const DefaultPropsProvider: React.ComponentType<DefaultPropsProviderProps>;

interface DefaultPropsProviderProps {
  /** Child components */
  children: React.ReactNode;
  
  /** Default props configuration */
  value: Record<string, any> | undefined;
}

/**
 * Hook to access default props for a component
 * @param params - Component name and props
 * @returns Merged props with defaults
 */
function useDefaultProps<Props>(params: {
  props: Props;
  name: string;
}): Props;

Usage Examples:

import { DefaultPropsProvider, useDefaultProps } from "@mui/system";

// Provider setup
const defaultProps = {
  Button: {
    variant: 'contained',
    color: 'primary',
  },
  TextField: {
    variant: 'outlined',
    fullWidth: true,
  },
};

function App() {
  return (
    <DefaultPropsProvider value={defaultProps}>
      <MyComponents />
    </DefaultPropsProvider>
  );
}

// Using in component
function MyButton(inProps) {
  const props = useDefaultProps({
    props: inProps,
    name: 'Button',
  });
  
  return <button {...props} />;
}

CSS Variables System (Unstable)

Advanced CSS custom properties system for dynamic theming and runtime theme switching with color scheme support.

/**
 * Create CSS variables provider for runtime theme switching
 * @param options - CSS variables provider configuration
 * @returns Provider component and utilities
 */
function unstable_createCssVarsProvider<
  ColorScheme extends string,
  Identifier extends string | undefined = undefined
>(
  options: CssVarsProviderConfig<ColorScheme> & {
    themeId?: Identifier;
    theme: any;
    resolveTheme?: (theme: any) => any;
  }
): CreateCssVarsProviderResult<ColorScheme, Identifier>;

interface CssVarsProviderConfig<ColorScheme extends string> {
  /** DOM attribute for applying color scheme (default: 'data-color-scheme') */
  attribute?: string;
  
  /** localStorage key for mode storage (default: 'mode') */
  modeStorageKey?: string;
  
  /** localStorage key for color scheme storage (default: 'color-scheme') */
  colorSchemeStorageKey?: string;
  
  /** Default color scheme configuration */
  defaultColorScheme: ColorScheme | { light: ColorScheme; dark: ColorScheme };
  
  /** Disable CSS transitions when switching themes */
  disableTransitionOnChange?: boolean;
  
  /** Force theme re-render when mode changes */
  forceThemeRerender?: boolean;
}

interface CreateCssVarsProviderResult<
  ColorScheme extends string,
  Identifier extends string | undefined
> {
  /** CSS variables provider component */
  CssVarsProvider: React.ComponentType<CssVarsProviderProps<ColorScheme>>;
  
  /** Hook to access color scheme state and controls */
  useColorScheme: () => ColorSchemeContextValue<ColorScheme>;
  
  /** Hook to get current color scheme without setters */
  getInitColorSchemeScript: (options?: InitColorSchemeScriptOptions) => React.ReactElement;
}

interface CssVarsProviderProps<ColorScheme extends string> {
  children: React.ReactNode;
  theme?: {
    cssVariables?: false;
    cssVarPrefix?: string;
    colorSchemes: Partial<Record<ColorScheme, any>>;
    colorSchemeSelector?: 'media' | 'class' | 'data' | string;
  };
  defaultMode?: 'light' | 'dark' | 'system';
  documentNode?: Document | null;
  colorSchemeNode?: Element | null;
  storageManager?: StorageManager | null;
  storageWindow?: Window | null;
  disableNestedContext?: boolean;
  disableStyleSheetGeneration?: boolean;
}

/**
 * Create CSS variable getter function
 * @param prefix - CSS variable prefix
 * @returns Function to get CSS variable reference
 */
function unstable_createGetCssVar(prefix?: string): (field: string) => string;

/**
 * Parse theme object into CSS variables
 * @param theme - Theme object to parse
 * @param options - Parsing options
 * @returns CSS variables object
 */
function unstable_cssVarsParser<Theme>(
  theme: Theme,
  options?: { prefix?: string }
): Record<string, string>;

/**
 * Prepare theme with CSS variables support
 * @param theme - Theme object
 * @param options - Preparation options
 * @returns Theme with CSS variables
 */
function unstable_prepareCssVars<Theme>(
  theme: Theme,
  options?: { prefix?: string }
): Theme & { cssVars: Record<string, string> };

/**
 * Create theme with CSS variables integration
 * @param options - Theme creation options
 * @returns Theme with CSS variables support
 */
function unstable_createCssVarsTheme<Theme>(options: any): Theme & {
  cssVars: Record<string, string>;
};

// Storage manager interface
interface StorageManager {
  get(key: string): string | null;
  set(key: string, value: string): void;
}

// Color scheme context value
interface ColorSchemeContextValue<SupportedColorScheme extends string> {
  mode: 'light' | 'dark' | 'system';
  setMode: (mode: 'light' | 'dark' | 'system') => void;
  colorScheme: SupportedColorScheme;
  setColorScheme: (colorScheme: SupportedColorScheme) => void;
  allColorSchemes: SupportedColorScheme[];
}

Usage Examples:

import { unstable_createCssVarsProvider, createTheme } from "@mui/system";

// Create theme with color schemes
const theme = createTheme({
  colorSchemes: {
    light: {
      palette: {
        primary: { main: '#1976d2' },
        background: { default: '#ffffff' },
      },
    },
    dark: {
      palette: {
        primary: { main: '#90caf9' },
        background: { default: '#121212' },
      },
    },
  },
});

// Create CSS variables provider
const { CssVarsProvider, useColorScheme } = unstable_createCssVarsProvider({
  themeId: 'my-theme',
  theme,
  defaultColorScheme: 'light',
});

// App with CSS variables support
function App() {
  return (
    <CssVarsProvider defaultMode="system">
      <MyComponent />
    </CssVarsProvider>
  );
}

// Component using color scheme
function ThemeSwitcher() {
  const { mode, setMode, colorScheme, setColorScheme } = useColorScheme();
  
  return (
    <div>
      <button onClick={() => setMode(mode === 'dark' ? 'light' : 'dark')}>
        Toggle {mode} mode
      </button>
      <p>Current color scheme: {colorScheme}</p>
    </div>
  );
}

// Using CSS variables in styles
const StyledComponent = styled('div')(({ theme }) => ({
  backgroundColor: 'var(--mui-palette-background-default)',
  color: 'var(--mui-palette-primary-main)',
  padding: theme.spacing(2),
}));

Theme Integration

The theme system integrates with all MUI System components and utilities:

  • System Props: All style functions automatically access theme values
  • sx Prop: Direct theme access with theme => theme.palette.primary.main syntax
  • Responsive Values: Breakpoint-aware styling using theme breakpoints
  • Component Overrides: Centralized component styling through theme configuration
  • CSS Variables: Automatic CSS custom property generation for dynamic theming

docs

components.md

css-in-js.md

index.md

style-functions.md

theme-system.md

utilities.md

tile.json