The CSS Configuration System provides modular configuration objects that define how style props map to CSS properties, with support for theme token resolution, value transformations, and responsive behavior. Each configuration module handles a specific category of CSS properties.
Core configuration interfaces that define how style properties are processed and mapped to CSS.
/**
* Configuration for individual CSS properties
* @param property - The CSS property name(s) to map to
* @param scale - Theme scale to use for token resolution
* @param transform - Function to transform the value before CSS output
* @param processResult - Whether to process the result through the CSS function
* @param static - Static styles to merge when this property is used
*/
interface PropConfig {
property?: string | string[] | ((theme: any) => string | string[]);
scale?: string;
transform?: (value: any, theme: any, styles: any) => any;
processResult?: boolean;
static?: Record<string, any> | ((theme: any) => Record<string, any>);
}
/**
* Record of property configurations
* @param key - Style property name
* @param value - Configuration object or true for pass-through
*/
interface Config {
[key: string]: PropConfig | true;
}
/**
* Creates configuration function for theme-aware properties
* @param scale - Theme scale identifier (e.g., 'colors', 'space')
* @param transform - Optional value transformation function
* @returns Configuration function for the property
*/
function toConfig(scale: string, transform?: Transform): (property: string) => PropConfig;
/**
* Creates logical property configuration for RTL/LTR support
* @param options - Configuration options with start/end property mappings
* @returns PropConfig with directional property mapping
*/
function logical(options: {
scale?: string;
property: {
ltr: string | string[];
rtl: string | string[];
};
}): PropConfig;Usage Examples:
import { Config, PropConfig, toConfig, logical } from "@chakra-ui/styled-system";
// Basic configuration
const customConfig: Config = {
// Pass-through configuration
display: true,
// Custom property mapping
bg: {
property: "backgroundColor",
scale: "colors"
},
// With transformation
rounded: {
property: "borderRadius",
scale: "radii",
transform: (value) => value === "full" ? "50%" : value
}
};
// Using configuration helpers
const colorConfig = toConfig("colors");
const spaceConfig = toConfig("space");
const myConfig: Config = {
textColor: colorConfig("color"),
spacing: spaceConfig("margin")
};
// Logical properties for internationalization
const logicalMargin: PropConfig = logical({
scale: "space",
property: {
ltr: "marginLeft",
rtl: "marginRight"
}
});Spacing properties for margin and padding with responsive support and logical properties for internationalization.
/**
* Configuration object for all spacing-related properties
*/
const space: Config;
/**
* TypeScript interface for spacing properties with theme token support
*/
interface SpaceProps {
/** Margin on all sides */
m?: Token<CSS.Property.Margin | number, "space">;
margin?: Token<CSS.Property.Margin | number, "space">;
/** Margin on individual sides */
mt?: Token<CSS.Property.MarginTop | number, "space">;
marginTop?: Token<CSS.Property.MarginTop | number, "space">;
mr?: Token<CSS.Property.MarginRight | number, "space">;
marginRight?: Token<CSS.Property.MarginRight | number, "space">;
mb?: Token<CSS.Property.MarginBottom | number, "space">;
marginBottom?: Token<CSS.Property.MarginBottom | number, "space">;
ml?: Token<CSS.Property.MarginLeft | number, "space">;
marginLeft?: Token<CSS.Property.MarginLeft | number, "space">;
/** Logical margin properties (RTL/LTR aware) */
ms?: Token<CSS.Property.MarginInlineStart | number, "space">;
marginStart?: Token<CSS.Property.MarginInlineStart | number, "space">;
marginInlineStart?: Token<CSS.Property.MarginInlineStart | number, "space">;
me?: Token<CSS.Property.MarginInlineEnd | number, "space">;
marginEnd?: Token<CSS.Property.MarginInlineEnd | number, "space">;
marginInlineEnd?: Token<CSS.Property.MarginInlineEnd | number, "space">;
/** Margin on axes */
mx?: Token<CSS.Property.Margin | number, "space">;
marginX?: Token<CSS.Property.Margin | number, "space">;
marginInline?: Token<CSS.Property.MarginInline | number, "space">;
my?: Token<CSS.Property.Margin | number, "space">;
marginY?: Token<CSS.Property.Margin | number, "space">;
marginBlock?: Token<CSS.Property.MarginBlock | number, "space">;
/** Padding properties - same pattern as margin */
p?: Token<CSS.Property.Padding | number, "space">;
padding?: Token<CSS.Property.Padding | number, "space">;
pt?: Token<CSS.Property.PaddingTop | number, "space">;
paddingTop?: Token<CSS.Property.PaddingTop | number, "space">;
pr?: Token<CSS.Property.PaddingRight | number, "space">;
paddingRight?: Token<CSS.Property.PaddingRight | number, "space">;
pb?: Token<CSS.Property.PaddingBottom | number, "space">;
paddingBottom?: Token<CSS.Property.PaddingBottom | number, "space">;
pl?: Token<CSS.Property.PaddingLeft | number, "space">;
paddingLeft?: Token<CSS.Property.PaddingLeft | number, "space">;
/** Logical padding properties */
ps?: Token<CSS.Property.PaddingInlineStart | number, "space">;
paddingStart?: Token<CSS.Property.PaddingInlineStart | number, "space">;
paddingInlineStart?: Token<CSS.Property.PaddingInlineStart | number, "space">;
pe?: Token<CSS.Property.PaddingInlineEnd | number, "space">;
paddingEnd?: Token<CSS.Property.PaddingInlineEnd | number, "space">;
paddingInlineEnd?: Token<CSS.Property.PaddingInlineEnd | number, "space">;
/** Padding on axes */
px?: Token<CSS.Property.Padding | number, "space">;
paddingX?: Token<CSS.Property.Padding | number, "space">;
paddingInline?: Token<CSS.Property.PaddingInline | number, "space">;
py?: Token<CSS.Property.Padding | number, "space">;
paddingY?: Token<CSS.Property.Padding | number, "space">;
paddingBlock?: Token<CSS.Property.PaddingBlock | number, "space">;
}Background-related CSS properties with color token support and gradient transformations.
/**
* Configuration object for background-related properties
*/
const background: Config;
/**
* TypeScript interface for background properties
*/
interface BackgroundProps {
/** Background color properties */
bg?: Token<CSS.Property.Color, "colors">;
background?: Token<CSS.Property.Color, "colors">;
bgColor?: Token<CSS.Property.Color, "colors">;
backgroundColor?: Token<CSS.Property.Color, "colors">;
/** Background image properties */
backgroundImage?: Token<CSS.Property.BackgroundImage, "gradients">;
bgImage?: Token<CSS.Property.BackgroundImage, "gradients">;
bgImg?: Token<CSS.Property.BackgroundImage, "gradients">;
bgGradient?: Token<CSS.Property.BackgroundImage, "gradients">;
/** Background positioning and sizing */
backgroundSize?: Token<CSS.Property.BackgroundSize | number>;
bgSize?: Token<CSS.Property.BackgroundSize | number>;
backgroundPosition?: Token<CSS.Property.BackgroundPosition | number>;
bgPosition?: Token<CSS.Property.BackgroundPosition | number>;
bgPos?: Token<CSS.Property.BackgroundPosition | number>;
/** Background behavior */
backgroundRepeat?: Token<CSS.Property.BackgroundRepeat>;
bgRepeat?: Token<CSS.Property.BackgroundRepeat>;
backgroundAttachment?: Token<CSS.Property.BackgroundAttachment>;
bgAttachment?: Token<CSS.Property.BackgroundAttachment>;
/** Background clipping with text support */
backgroundClip?: Token<CSS.Property.BackgroundClip | "text">;
bgClip?: Token<CSS.Property.BackgroundClip | "text">;
}Layout properties including sizing, display, overflow, and positioning.
/**
* Configuration object for layout-related properties
*/
const layout: Config;
/**
* TypeScript interface for layout properties
*/
interface LayoutProps {
/** Size properties */
width?: Token<CSS.Property.Width | number, "sizes">;
w?: Token<CSS.Property.Width | number, "sizes">;
height?: Token<CSS.Property.Height | number, "sizes">;
h?: Token<CSS.Property.Height | number, "sizes">;
/** Combined size properties */
boxSize?: Token<CSS.Property.Width | number, "sizes">;
inlineSize?: Token<CSS.Property.InlineSize | number, "sizes">;
blockSize?: Token<CSS.Property.BlockSize | number, "sizes">;
/** Min/max dimensions */
minWidth?: Token<CSS.Property.MinWidth | number, "sizes">;
minW?: Token<CSS.Property.MinWidth | number, "sizes">;
maxWidth?: Token<CSS.Property.MaxWidth | number, "sizes">;
maxW?: Token<CSS.Property.MaxWidth | number, "sizes">;
minHeight?: Token<CSS.Property.MinHeight | number, "sizes">;
minH?: Token<CSS.Property.MinHeight | number, "sizes">;
maxHeight?: Token<CSS.Property.MaxHeight | number, "sizes">;
maxH?: Token<CSS.Property.MaxHeight | number, "sizes">;
/** Display and visibility */
display?: Token<CSS.Property.Display>;
hideFrom?: ResponsiveValue<string>;
hideBelow?: ResponsiveValue<string>;
visibility?: Token<CSS.Property.Visibility>;
/** Overflow and scroll behavior */
overflow?: Token<CSS.Property.Overflow>;
overflowX?: Token<CSS.Property.OverflowX>;
overflowY?: Token<CSS.Property.OverflowY>;
overscrollBehavior?: Token<CSS.Property.OverscrollBehavior>;
/** Box model */
boxSizing?: Token<CSS.Property.BoxSizing>;
aspectRatio?: Token<CSS.Property.AspectRatio | number>;
verticalAlign?: Token<CSS.Property.VerticalAlign>;
/** Positioning context */
float?: Token<CSS.Property.Float>;
objectFit?: Token<CSS.Property.ObjectFit>;
objectPosition?: Token<CSS.Property.ObjectPosition>;
isolation?: Token<CSS.Property.Isolation>;
}Complete configuration objects for all CSS property categories:
/** Border properties configuration */
const border: Config;
interface BorderProps { /* border-related properties */ }
/** Color properties configuration */
const color: Config;
interface ColorProps { /* color-related properties */ }
/** Visual effects configuration */
const effect: Config;
interface EffectProps { /* shadow, opacity, blend mode properties */ }
/** CSS filters configuration */
const filter: Config;
interface FilterProps { /* filter and backdrop-filter properties */ }
/** Flexbox properties configuration */
const flexbox: Config;
interface FlexboxProps { /* flex container and item properties */ }
/** CSS Grid properties configuration */
const grid: Config;
interface GridProps { /* grid container and item properties */ }
/** Interactivity properties configuration */
const interactivity: Config;
interface InteractivityProps { /* cursor, pointer-events, user-select */ }
/** List styling configuration */
const list: Config;
interface ListProps { /* list-style properties */ }
/** Miscellaneous properties configuration */
const others: Config;
interface OthersProps { /* transform, clip, and other properties */ }
/** Positioning properties configuration */
const position: Config;
interface PositionProps { /* position, top, right, bottom, left, z-index */ }
/** Ring/outline effects configuration */
const ring: Config;
interface RingProps { /* ring, ring-color, ring-offset properties */ }
/** Scroll properties configuration */
const scroll: Config;
interface ScrollProps { /* scroll-behavior, scroll-margin properties */ }
/** Text decoration configuration */
const textDecoration: Config;
interface TextDecorationProps { /* text-decoration properties */ }
/** CSS transforms configuration */
const transform: Config;
interface TransformProps { /* transform, rotate, scale, translate */ }
/** CSS transitions configuration */
const transition: Config;
interface TransitionProps { /* transition properties */ }
/** Typography configuration */
const typography: Config;
interface TypographyProps { /* font, text, and typography properties */ }Import Examples:
// Import all configurations
import {
space, background, layout, border, color, effect, filter,
flexbox, grid, interactivity, list, others, position,
ring, scroll, textDecoration, transform, transition, typography
} from "@chakra-ui/styled-system/config";
// Import specific interfaces
import type {
SpaceProps, BackgroundProps, LayoutProps, FlexboxProps
} from "@chakra-ui/styled-system/config";
// Create combined props interface
interface MyComponentProps extends SpaceProps, LayoutProps, FlexboxProps {
customProp?: string;
}
// Use in component styling
const buttonConfig = {
...space,
...layout,
...color,
...typography
};