Theme

Typography

To manage Typography options, the theme object supports the following keys:

• fonts (font families)
• fontSizes
• fontWeights
• lineHeights
• letterSpacings

// example theme object
export default {
  colors: {...},
  fonts: {
    heading: `'Inter', -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"`,
    body: `'Inter', -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"`,
    mono: `SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace`
  },
  fontSizes: [12, 14, 16, 20, 24, 28, 32, 36, 48, 64, 96, 128],
  fontWeights: {
    hairline: 100,
    thin: 200,
    light: 300,
    normal: 400,
    medium: 500,
    semibold: 600,
    bold: 700,
    extrabold: 800,
    black: 900
  },
  lineHeights: {
    normal: "normal",
    none: "1",
    shorter: "1.333",
    short: "1.4",
    base: "1.5",
    tall: "1.625",
    taller: "2"
  },
  letterSpacings: {
    tighter: "-0.02em",
    tight: "-0.01em",
    normal: "0",
    wide: "0.025em",
    wider: "0.05em",
    widest: "0.1em"
  }
};// example theme objectexport default {  colors: {...},  fonts: {    heading: `'Inter', -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"`,    body: `'Inter', -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"`,    mono: `SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace`  },  fontSizes: [12, 14, 16, 20, 24, 28, 32, 36, 48, 64, 96, 128],  fontWeights: {    hairline: 100,    thin: 200,    light: 300,    normal: 400,    medium: 500,    semibold: 600,    bold: 700,    extrabold: 800,    black: 900  },  lineHeights: {    normal: "normal",    none: "1",    shorter: "1.333",    short: "1.4",    base: "1.5",    tall: "1.625",    taller: "2"  },  letterSpacings: {    tighter: "-0.02em",    tight: "-0.01em",    normal: "0",    wide: "0.025em",    wider: "0.05em",    widest: "0.1em"  }};

Breakpoints

To configure the default breakpoints used in responsive array values, add a breakpoints array to your theme. These values will be used to generate mobile-first (i.e. min-width) media queries, which can then be used to apply responsive styles.

For example, you can write <Box fontSize={["14px", "16px"]}/> to make the fontSize responsive.

// theme.js
export default {
  breakpoints: ['30em', '48em', '62em', '80em'],
};// theme.jsexport default {  breakpoints: ['30em', '48em', '62em', '80em'],};

Spacing

The space key allows you to customize the global spacing and sizing scale for your project. By default these spacing value can be referenced by the padding, margin, and top, left, right, bottom styles.

export default {
  space: {
    0: '0',
    px: '1px',
    1: '0.25rem',
    2: '0.5rem',
    3: '0.75rem',
    4: '1rem',
    5: '1.25rem',
    6: '1.5rem',
    8: '2rem',
    10: '2.5rem',
    12: '3rem',
    16: '4rem',
    20: '5rem',
    24: '6rem',
    32: '8rem',
    40: '10rem',
    48: '12rem',
    56: '14rem',
    64: '16rem',
  },
};export default {  space: {    0: '0',    px: '1px',    1: '0.25rem',    2: '0.5rem',    3: '0.75rem',    4: '1rem',    5: '1.25rem',    6: '1.5rem',    8: '2rem',    10: '2.5rem',    12: '3rem',    16: '4rem',    20: '5rem',    24: '6rem',    32: '8rem',    40: '10rem',    48: '12rem',    56: '14rem',    64: '16rem',  },};

By default, Stacks UI includes a comprehensive numeric spacing scale inspired by Tailwind CSS. The values are proportional, so 1 spacing unit is equal to 0.25rem, which translates to 4px by default in common browsers.

Mental model: If you need a spacing of 40px, divide it by 4. That'll give you 10. Then use it in your component as ml={10}.

Sizes

The sizes key allows you to customize the global sizing of components you build for your project. By default these spacing value can be referenced by the width, height, and maxWidth, minWidth, maxHeight, minHeight styles.

export default {
  sizes: {
    ...theme.space,
    full: '100%',
    '3xs': '14rem',
    '2xs': '16rem',
    xs: '20rem',
    sm: '24rem',
    md: '28rem',
    lg: '32rem',
    xl: '36rem',
    '2xl': '42rem',
    '3xl': '48rem',
    '4xl': '56rem',
    '5xl': '64rem',
    '6xl': '72rem',
  },
};export default {  sizes: {    ...theme.space,    full: '100%',    '3xs': '14rem',    '2xs': '16rem',    xs: '20rem',    sm: '24rem',    md: '28rem',    lg: '32rem',    xl: '36rem',    '2xl': '42rem',    '3xl': '48rem',    '4xl': '56rem',    '5xl': '64rem',    '6xl': '72rem',  },};

For a component like this: <Box w={4} h={3} /> will generate an empty div with width set to 1rem or 16px and height set to 0.75rem or 12px

Configuration reference

Except for breakpoints, colors, and spacing, all of the keys in the theme object map to one of Stacks UI's core theme. All of these keys can be replaced or extended.

See the full reference table of properties.