Build-variants

Declaratively build style objects from your React component props with a clean, type-safe API.

Introduction

Build-variants helps you organize and compose CSS, or any other style values, from component props. It keeps styling logic separate from component logic, which makes your code easier to maintain and extend. It is a builder: it does not apply styles itself, but instead returns an object that your CSS-in-JS library can consume.

Installation

npm install @productive-codebases/build-variants

Usage

1. Set Up Your Factory Function

Configure build-variants for your styling engine. For example, with styled-components:

import type { CSSObject } from '@emotion/react'
import { newBuildVariants } from '@productive-codebases/build-variants'

export function buildVariants<TProps extends object>(props: TProps) {
  return newBuildVariants<TProps, CSSObject>(props)
}

This creates a helper that takes props and returns a builder configured for CSSObject styles.

2. Decorate a Component

Use the builder with any styled function that accepts a CSSObject-like object. Whether you are using Emotion, styled-components, MUI, or another library, the generated style object fits naturally into the existing API.

import styled from '@emotion/styled'
// Alternatively:
// import styled from 'styled-components'
// or import { styled } from '@mui/material', etc.
import { buildVariants } from './buildVariants'

const Div = styled.div(props => buildVariants(props).end())

export default function Button() {
  return <Div>My Button</Div>
}

In this example, no additional styles are defined, so the builder returns an empty style object.

3. Adding CSS Blocks

Chain CSS blocks to add styles incrementally:

const Div = styled.div(props => {
  return buildVariants(props)
    .css({
      display: 'inline-block',
      padding: '10px'
    })
    .css({
      background: 'blue',
      color: 'white'
    })
    .end()
})

Applied styles:

• display: inline-block
• padding: 10px
• background: blue
• color: white

4. Declaring Variants

Simple Variant

Define a style variant from a single prop value:

import styled from '@emotion/styled'
import { buildVariants } from './buildVariants'

interface IButtonProps {
  type: 'primary' | 'secondary'
}

const Div = styled.div<IButtonProps>(props => {
  return buildVariants(props)
    .css({
      display: 'inline-block',
      padding: '10px'
    })
    .variant('type', props.type, {
      primary: {
        background: 'blue',
        color: 'white'
      },
      secondary: {
        background: 'silver',
        color: 'black'
      }
    })
    .end()
})

export default function Button(props: IButtonProps) {
  return <Div type={props.type}>My Button</Div>
}

Applied styles:

• When type="primary":

  • Base styles: display: inline-block, padding: 10px
  • Variant styles: background: blue, color: white

• When type="secondary":

  • Base styles: display: inline-block, padding: 10px
  • Variant styles: background: silver, color: black

Multiple Variants

Allow multiple variant values, for example to compose text styles:

interface IButtonProps {
  type: 'primary' | 'secondary'
  text?: Array<'strong' | 'success' | 'error'>
}

const Div = styled.div<IButtonProps>(props => {
  return buildVariants(props)
    .css({
      display: 'inline-block',
      padding: '10px'
    })
    .variant('type', props.type, {
      primary: {
        background: 'blue',
        color: 'white'
      },
      secondary: {
        background: 'silver',
        color: 'black'
      }
    })
    .variants('text', props.text, {
      strong: { fontWeight: 'bold' },
      success: { color: 'green' },
      error: { color: 'red' }
    })
    .end()
})

Example usage:

// Renders a primary button with both bold and red text styles
<Button type="primary" text={['strong', 'error']} />

Applied styles:

• Type "primary": background: blue, color: white
• Text variants:
  • strong adds fontWeight: bold
  • error adds color: red

Note: If styles conflict, for example when two variants set color, the later applied style wins.

Compound Variants

Compose multiple variants by combining private (internal) and public (external) props:

interface IButtonProps {
  // Private variants used to compose public ones
  _background?: 'primary' | 'secondary' | 'success' | 'error'
  _text?: Array<'dark' | 'light' | 'success' | 'error' | 'strong'>
  // Public variant exposed by the component API
  type: 'primary' | 'secondary' | 'success' | 'error'
  children: string
}

const Div = styled.div<IButtonProps>(props => {
  return buildVariants(props)
    .css({
      display: 'inline-block',
      padding: '10px'
    })
    // Define private variants first.
    .variant('_background', props._background, {
      primary: { background: 'blue' },
      secondary: { background: 'silver' },
      success: { background: '#eaff96' },
      error: { background: '#ffdbdb' }
    })
    .variants('_text', props._text, {
      dark: { color: 'black' },
      light: { color: 'white' },
      success: { color: 'green' },
      error: { color: 'red' },
      strong: { fontWeight: 'bold' }
    })
    // Map the public `type` prop to the private variants.
    .compoundVariant('type', props.type, {
      primary: builder_ =>
        builder_.get('_background', 'primary').get('_text', ['light']).end(),
      secondary: builder_ =>
        builder_.get('_background', 'secondary').get('_text', ['dark']).end(),
      success: builder_ =>
        builder_.get('_background', 'success').get('_text', ['success']).end(),
      error: builder_ =>
        builder_
          .get('_background', 'error')
          .get('_text', ['error', 'strong'])
          .css({ border: '1px solid red' })
          .end()
    })
    .end()
})

Usage examples:

<Button type="primary">Primary button</Button>
<Button type="secondary">Secondary button</Button>
<Button type="success">Success button</Button>
<Button type="error">Error button</Button>

Applied styles:

• Primary:

  • Private _background: primary → background: blue
  • Private _text: ['light'] → color: white

• Secondary:

  • Private _background: secondary → background: silver
  • Private _text: ['dark'] → color: black

• Success:

  • Private _background: success → background: #eaff96
  • Private _text: ['success'] → color: green

• Error:

  • Private _background: error → background: #ffdbdb
  • Private _text: ['error', 'strong'] → color: red and fontWeight: bold
  • Additional style: border: 1px solid red

5. Overriding with Private Variants

Private variants take precedence over public ones, which lets you override the default behavior for specific use cases.

<Button type="error">Error button</Button>

<Button type="error" _background="success">
  Error button with success background
</Button>

Applied styles:

• The first button uses the default compound variant for error.
• The second button overrides _background with "success", so it receives background: #eaff96 while keeping the other error-related styles.

6. Conditional Blocks

Apply or skip blocks of styles based on a condition:

const Div = styled.div<IButtonProps>(props => {
  return buildVariants(props)
    // Other style blocks…
    .if(props.applyTextVariant === true, builder_ => {
      return builder_
        .variants('_text', props._text, {
          dark: { color: 'black' },
          light: { color: 'white' },
          success: { color: 'green' },
          error: { color: 'red' },
          strong: { fontWeight: 'bold' }
        })
        .end()
    })

    // Alternatively, if you only need to add simple CSS:
    // .if(props.applyTextVariant === true, {
    //   color: 'red'
    // })

    .compoundVariant('type', props.type, {
      // …
    })
    .end()
})

Applied styles:

• If applyTextVariant is true, the text-related styles are applied. Otherwise, they are omitted.

7. Blocks Weight

Control the order in which styles are applied by assigning a weight to each block:

const Div = styled.div<IButtonProps>(props => {
  return buildVariants(props)
    .css({
      display: 'inline-block',
      padding: '10px'
    })
    .css(
      { color: 'silver' },
      { weight: 10 }  // This block is applied later.
    )
    .variants('_text', props._text, {
      dark: { color: 'black' },
      // …
    })
    .end()
})

Applied styles:

• The color: silver block has weight 10, so it overrides any earlier conflicting color value from _text.

8. Debugging

Log the internal builder state to help diagnose complex style composition:

const Div = styled.div<IButtonProps>(props => {
  return buildVariants(props)
    // Other style definitions…
    .debug()
    .end()
})

Or enable debugging conditionally:

interface IButtonProps {
  debug?: boolean
}

const Div = styled.div<IButtonProps>(props => {
  return buildVariants(props)
    // Other style definitions…
    .debug(props.debug === true)
    .end()
})

Result: Detailed console output shows which styles are applied and what the builder contains internally.

Examples

• https://codesandbox.io/s/1-init-b5t24e?file=/src/buildVariants.ts
• https://codesandbox.io/s/1-init-b5t24e?file=/src/Button.tsx
• https://codesandbox.io/s/2-add-css-0zmimn?file=/src/Button.tsx
• https://codesandbox.io/s/3-add-variant-9b3bvh?file=/src/Button.tsx
• https://codesandbox.io/s/4-multiple-variants-v9bxds?file=/src/Button.tsx
• https://codesandbox.io/s/5-variants-composition-m6b5zs?file=/src/Button.tsx
• https://codesandbox.io/s/overrides-with-private-variants-w72ed1?file=/src/App.tsx
• https://codesandbox.io/s/7-condition-blocks-0xko7x?file=/src/Button.tsx
• https://codesandbox.io/s/8-blocks-weight-d0fbz3?file=/src/Button.tsx
• https://codesandbox.io/s/9-debug-f6ozbu?file=/src/Button.tsx:463-2386

Summary

Build-variants helps you:

• Declare and compose style variants with a clean, declarative, and type-safe API.
• Separate styling logic from component code.
• Support multiple, compound, and conditional variants for flexible component design.
• Control style precedence with block weights.
• Debug style composition effortlessly.

Use Build-variants to build UI components that stay flexible, explicit, and easier to maintain.