or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

breakpoints.mdcolor.mdcomponent.mdcss-calc.mdcss-var.mdindex.md
tile.json

tessl/npm-chakra-ui--theme-tools

Set of helpers that makes theming and styling easier

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@chakra-ui/theme-tools@2.2.x

To install, run

npx @tessl/cli install tessl/npm-chakra-ui--theme-tools@2.2.0

index.mddocs/

Chakra UI Theme Tools

Chakra UI Theme Tools provides a comprehensive set of utility functions and helpers designed to simplify theming and styling in React applications, particularly within the Chakra UI ecosystem. It offers powerful color manipulation utilities, CSS variable management tools, component styling helpers, breakpoint creation utilities, and CSS calculation functions for dynamic styling computations.

Package Information

  • Package Name: @chakra-ui/theme-tools
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @chakra-ui/theme-tools

Core Imports

import { 
  getColor, tone, darken, lighten, 
  mode, cssVar, calc, createBreakpoints,
  anatomy 
} from "@chakra-ui/theme-tools";

For selective imports from sub-modules:

import { getColor, darken, lighten } from "@chakra-ui/theme-tools/color";
import { mode, orient } from "@chakra-ui/theme-tools/component";
import { cssVar } from "@chakra-ui/theme-tools/css-var";
import { calc } from "@chakra-ui/theme-tools/css-calc";
import { createBreakpoints } from "@chakra-ui/theme-tools/create-breakpoints";

Note: All sub-module imports correspond to the package's export paths. The package provides dedicated exports for each module.

CommonJS:

const { getColor, tone, darken, lighten, mode, cssVar, calc } = require("@chakra-ui/theme-tools");

Basic Usage

import { getColor, darken, lighten, mode, cssVar } from "@chakra-ui/theme-tools";

// Theme-aware color operations
const theme = {
  colors: {
    blue: { 500: "#3182ce", 600: "#2c5282" },
    gray: { 100: "#f7fafc", 800: "#2d3748" }
  }
};

// Get colors from theme
const primaryColor = getColor(theme, "blue.500"); // "#3182ce"

// Color manipulations
const darkerBlue = darken("blue.500", 10)(theme); // Darken by 10%
const lighterBlue = lighten("blue.500", 20)(theme); // Lighten by 20% (NOTE: Currently returns undefined due to bug)

// Color mode utilities
const backgroundColor = mode("gray.100", "gray.800")({ colorMode: "light" }); // "gray.100"

// CSS variables
const bgVar = cssVar("background-color");
// Returns: { variable: "--background-color", reference: "var(--background-color)" }

Architecture

Chakra UI Theme Tools is organized around several key functional areas:

  • Color System: Advanced color manipulation with theme integration including tone detection, accessibility checking, and mathematical color operations
  • Component Helpers: Utilities for theme-aware component styling including color mode switching and orientation handling
  • CSS Variables: Tools for creating and managing CSS custom properties with proper escaping and fallbacks
  • Breakpoint Management: Utilities for responsive design breakpoint configuration
  • CSS Calculations: Type-safe CSS calc() expression builder with chainable operations
  • Component Anatomy: Re-exported anatomy system for consistent component part naming

Capabilities

Color Manipulation

Advanced color manipulation utilities including theme-aware color operations, accessibility calculations, and color transformations. Essential for building consistent color systems and ensuring WCAG compliance.

type Dict = { [key: string]: any };

function getColor(theme: Dict, color: string, fallback?: string): string;
function tone(color: string): (theme: Dict) => "light" | "dark";
function darken(color: string, amount: number): (theme: Dict) => string;
function lighten(color: string, amount: number): (theme: Dict) => string; // NOTE: Has bug - missing return statement
function contrast(fg: string, bg: string): (theme: Dict) => number;
function isAccessible(
  textColor: string, 
  bgColor: string, 
  options?: WCAG2Params
): (theme: Dict) => boolean;

interface WCAG2Params {
  level?: "AA" | "AAA";
  size?: "large" | "small";
}

Color Manipulation

Component Styling

Theme-aware component styling helpers for handling color modes, orientations, and responsive behavior in component systems.

function mode<T>(light: T, dark: T): (props: StyleFunctionProps) => T;
function orient<T>(options: {
  orientation?: "vertical" | "horizontal";
  vertical: T;
  horizontal: T;
}): T | {};

type StyleFunctionProps = {
  colorMode?: "light" | "dark";
  orientation?: "vertical" | "horizontal";
  [key: string]: any;
};

Component Styling

CSS Variables

CSS custom property management with automatic escaping, prefixing, and fallback support for robust theming systems.

function cssVar(name: string, options?: CSSVarOptions): CSSVar;
function toVar(value: string, prefix?: string): string;
function toVarRef(name: string, fallback?: string): string;

interface CSSVar {
  variable: string;
  reference: string;
}

interface CSSVarOptions {
  fallback?: string | CSSVar;
  prefix?: string;
}

CSS Variables

CSS Calculations

Type-safe CSS calc() expression builder with chainable operations for dynamic styling and responsive calculations.

function calc(x: Operand): CalcChain;

interface CalcChain {
  add: (...operands: Operand[]) => CalcChain;
  subtract: (...operands: Operand[]) => CalcChain;
  multiply: (...operands: Operand[]) => CalcChain;
  divide: (...operands: Operand[]) => CalcChain;
  negate: () => CalcChain;
  toString: () => string;
}

type Operand = string | number | CSSVar;

CSS Calculations

Breakpoints

Responsive design breakpoint configuration utilities for creating consistent breakpoint systems.

function createBreakpoints<T extends BaseBreakpointConfig>(
  config: T
): Breakpoints<T>;

interface BaseBreakpointConfig {
  sm: string;
  md: string;
  lg: string;
  xl: string;
  "2xl"?: string;
  [key: string]: string | undefined;
}

type Breakpoints<T> = T & { base: "0em" };

Breakpoints

Component Anatomy

Component anatomy system for consistent component part naming and theming. Re-exported from @chakra-ui/anatomy.

function anatomy<T extends string = string>(
  name: string,
  map?: any
): Anatomy<T>;

interface Anatomy<T extends string> {
  toPart: (part: string) => AnatomyPart;
  parts: <U extends string>(...parts: U[]) => AnatomyInstance<U>;
  extend: <V extends string>(...parts: V[]) => AnatomyInstance<T | V>;
  readonly keys: T[];
  selectors: () => Record<T, string>;
  classnames: () => Record<T, string>;
  __type: T;
}

interface AnatomyPart {
  selector: string;
  className: string;
  toString(): string;
}

type AnatomyInstance<T extends string> = Omit<Anatomy<T>, "parts">;
type AnatomyPartName<T> = T extends AnatomyInstance<infer U> ? U : never;

Usage Example:

import { anatomy } from "@chakra-ui/theme-tools";

// Define button component anatomy
const buttonAnatomy = anatomy("button").parts("root", "icon", "label");

// Get selectors and class names
const selectors = buttonAnatomy.selectors();
// Returns: { root: ".chakra-button", icon: ".chakra-button__icon", label: ".chakra-button__label" }

const classNames = buttonAnatomy.classnames();
// Returns: { root: "chakra-button", icon: "chakra-button__icon", label: "chakra-button__label" }

// Use in theme definitions
const buttonTheme = {
  parts: buttonAnatomy.keys,
  baseStyle: {
    [buttonAnatomy.keys[0]]: { // root
      display: "inline-flex",
      alignItems: "center"
    },
    [buttonAnatomy.keys[1]]: { // icon
      marginRight: 2
    }
  }
};