or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

custom-icons.mdicon-components.mdindex.mdtheming.md
tile.json

theming.mddocs/

Theming and Customization

Comprehensive theming system that integrates with styled-components for consistent color schemes and sizing across applications.

Capabilities

Base Theme

The default theme configuration that provides standard colors and sizes.

declare const base: {
  global: {
    colors: {
      icon: string;
    };
  };
  icon: {
    size: {
      small: string;
      medium: string;
      large: string;
      xlarge: string;
    };
  };
};

The base theme provides:

  • global.colors.icon: Default icon color (#666666)
  • icon.size.small: 12px
  • icon.size.medium: 24px (default)
  • icon.size.large: 48px
  • icon.size.xlarge: 96px

Usage Example:

import { ThemeProvider } from 'styled-components';
import { base } from 'grommet-icons';
import { Add, Close } from 'grommet-icons';

function App() {
  return (
    <ThemeProvider theme={base}>
      <Add />
      <Close />
    </ThemeProvider>
  );
}

Deep Merge Utility

Utility function for merging custom theme configurations with the base theme.

/**
 * Deep merge multiple objects, preserving nested structure
 * @param target - Base object to merge into
 * @param sources - Source objects to merge from
 * @returns Merged object with combined properties
 */
declare function deepMerge(target: any, ...sources: any[]): any;

Usage Examples:

import { ThemeProvider } from 'styled-components';
import { base, deepMerge } from 'grommet-icons';
import { Add, Close, Facebook } from 'grommet-icons';

// Custom theme with brand colors
const customTheme = deepMerge(base, {
  global: {
    colors: {
      brand: '#ff6600',
      accent: '#0066cc',
      icon: '#333333', // Override default icon color
    },
  },
});

function App() {
  return (
    <ThemeProvider theme={customTheme}>
      <Add color="brand" />
      <Close color="accent" />
      <Facebook /> {/* Uses default icon color */}
    </ThemeProvider>
  );
}

Custom Sizing

Extend the theme with custom icon sizes beyond the standard options.

interface CustomTheme {
  global: {
    colors: {
      [colorName: string]: string | { light?: string; dark?: string };
    };
  };
  icon: {
    size: {
      small: string;
      medium: string;
      large: string;
      xlarge: string;
      [customSize: string]: string;
    };
    extend?: any; // Custom CSS extensions
  };
}

Usage Examples:

import { deepMerge, base } from 'grommet-icons';
import { Add, Menu } from 'grommet-icons';

// Theme with custom sizes
const sizeTheme = deepMerge(base, {
  icon: {
    size: {
      tiny: '8px',
      huge: '128px',
      responsive: '2rem',
    },
  },
});

function MyComponent() {
  return (
    <ThemeProvider theme={sizeTheme}>
      <Add size="tiny" />
      <Menu size="huge" />
      <Add size="responsive" />
    </ThemeProvider>
  );
}

Color System

The theming system supports various color specification methods.

interface ColorSystem {
  /** Direct CSS color values */
  directColor: string; // '#ff0000', 'red', 'rgb(255,0,0)'
  
  /** Theme color names */
  themeColor: string; // 'brand', 'accent', 'text'
  
  /** Light/dark color objects */
  adaptiveColor: {
    light?: string;
    dark?: string;
  };
  
  /** Plain color preservation */
  plain: 'plain'; // Preserves original SVG colors
}

Usage Examples:

import { deepMerge, base } from 'grommet-icons';
import { Add, Facebook, StatusGood } from 'grommet-icons';

// Theme with light/dark color support
const adaptiveTheme = deepMerge(base, {
  global: {
    colors: {
      brand: {
        light: '#0066cc',
        dark: '#4d9fff',
      },
      success: '#00cc66',
      error: '#ff3333',
    },
  },
  dark: true, // Enable dark mode
});

function ThemedIcons() {
  return (
    <ThemeProvider theme={adaptiveTheme}>
      {/* Uses adaptive brand color */}
      <Add color="brand" />
      
      {/* Direct CSS color */}
      <Add color="#ff6600" />
      
      {/* Theme color name */}
      <StatusGood color="success" />
      
      {/* Preserve original colors */}
      <Facebook color="plain" />
    </ThemeProvider>
  );
}

Default Props Extension

Extend default properties for all icons in an application.

interface DefaultProps {
  theme: any;
}

declare const defaultProps: DefaultProps;

/**
 * Extend the default theme applied to all icons
 * @param theme - Theme object to merge with base theme
 */
declare function extendDefaultTheme(theme: any): void;

Usage Example:

import { extendDefaultTheme, base, deepMerge } from 'grommet-icons';

// Set global default theme
const appTheme = deepMerge(base, {
  global: {
    colors: {
      icon: '#2d3748',
      brand: '#3182ce',
    },
  },
  icon: {
    size: {
      medium: '20px', // Override default medium size
    },
  },
});

extendDefaultTheme(appTheme);

// Now all icons use the extended theme by default

CSS Extensions

Extend icon styling with custom CSS through the theme system.

interface ThemeExtensions {
  icon: {
    extend?: string | TemplateStringsArray | Function;
  };
}

Usage Examples:

import { css } from 'styled-components';
import { deepMerge, base } from 'grommet-icons';

// Theme with custom CSS extensions
const extendedTheme = deepMerge(base, {
  icon: {
    extend: css`
      transition: all 0.2s ease;
      cursor: pointer;
      
      &:hover {
        transform: scale(1.1);
        opacity: 0.8;
      }
    `,
  },
});

// Or with a function for dynamic styling
const dynamicTheme = deepMerge(base, {
  icon: {
    extend: (props) => css`
      transition: color 0.2s ease;
      ${props.interactive && `
        cursor: pointer;
        &:hover {
          color: ${props.theme.global.colors.brand};
        }
      `}
    `,
  },
});

Dark Mode Support

The theming system supports automatic light/dark mode switching.

Usage Example:

import { deepMerge, base } from 'grommet-icons';
import { Add, Close, Menu } from 'grommet-icons';

const darkModeTheme = deepMerge(base, {
  global: {
    colors: {
      icon: {
        light: '#2d3748',
        dark: '#e2e8f0',
      },
      brand: {
        light: '#3182ce',
        dark: '#63b3ed',
      },
    },
  },
  dark: true, // Enable dark mode
});

function DarkModeApp() {
  return (
    <ThemeProvider theme={darkModeTheme}>
      <Add />        {/* Uses dark mode icon color */}
      <Close color="brand" /> {/* Uses dark mode brand color */}
      <Menu color="#ffffff" /> {/* Direct color override */}
    </ThemeProvider>
  );
}

Theme Integration

interface ThemeProvider {
  theme: {
    global: {
      colors: Record<string, string | { light?: string; dark?: string }>;
    };
    icon: {
      size: Record<string, string>;
      extend?: any;
    };
    dark?: boolean;
  };
}

The grommet-icons theming system integrates seamlessly with styled-components ThemeProvider, allowing for consistent design systems across entire applications.

Utility Functions

Additional utility functions are available for advanced theming and icon manipulation.

/**
 * Check if a value is a plain object
 * @param item - Value to check
 * @returns True if item is a plain object
 */
declare function isObject(item: any): boolean;

/**
 * Extract numeric value from CSS string (e.g., "24px" -> 24)
 * @param string - CSS value string
 * @returns Parsed numeric value
 */
declare function parseMetricToNum(string?: string): number;

/**
 * React hook for handling icon stroke scaling at small sizes
 * @param props - Icon props including size
 * @returns Props object with vectorEffect if needed
 */
declare function useScaleProps(props: { size?: string }): { vectorEffect?: string };

/**
 * Calculate padding for icon alignment with text
 * @param props - Props including height, width, size
 * @returns CSS padding string
 */
declare function iconPad(props: {
  height?: string;
  width?: string;
  size?: string;
}): string;

/**
 * Generate unique ID prefix for SVG elements to avoid collisions
 * @param name - Base name for the prefix
 * @returns Unique prefix string
 */
declare function generatePrefix(name: string): string;

These utilities are primarily used internally but are available for advanced customization scenarios.