https://github.com/productive-codebases/build-variants
Declare and compose styles variants with ease.
https://github.com/productive-codebases/build-variants
css css-in-js design-system react styled-components styling typescript
Last synced: 9 months ago
JSON representation
Declare and compose styles variants with ease.
- Host: GitHub
- URL: https://github.com/productive-codebases/build-variants
- Owner: productive-codebases
- License: mit
- Created: 2022-06-27T17:58:33.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2025-03-10T16:50:23.000Z (over 1 year ago)
- Last Synced: 2025-09-10T11:03:02.904Z (10 months ago)
- Topics: css, css-in-js, design-system, react, styled-components, styling, typescript
- Language: TypeScript
- Homepage:
- Size: 616 KB
- Stars: 6
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Build-variants
Declaratively build style objects based on your React component props with a clean, type-safe API.
---
## Introduction
**Build-variants** helps you organize and compose CSS (or any style values) based on component props. It separates styling logic from component logic, making your code easier to maintain and extend. Note that it is a *builder*—it doesn’t apply styles by itself but returns an object your CSS-in-JS library can use.
---
## Installation
```bash
npm install @productive-codebases/build-variants
```
---
## Usage
### 1. Setup Your Factory Function
Configure **build-variants** with your styling engine. For example, with _styled-components_:
```ts
import type { CSSObject } from '@emotion/react'
import { newBuildVariants } from '@productive-codebases/build-variants'
export function buildVariants(props: TProps) {
return newBuildVariants(props)
}
```
*This sets up a function that accepts props and returns a builder configured for CSSObject objects.*
---
### 2. Decorate a Component
Integrate the builder with any styled function that accepts a CSSObject-like object. Whether you're using Emotion, styled-components, MUI, or any other library, the generated style object will work seamlessly.
```tsx
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
My Button
}
```
*In this example, no extra styles are added; the builder returns an empty style object.*
---
### 3. Adding CSS Blocks
Chain CSS blocks to add styles:
```ts
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 based on a prop value:
```tsx
import styled from '@emotion/styled'
import { buildVariants } from './buildVariants'
interface IButtonProps {
type: 'primary' | 'secondary'
}
const Div = styled.div(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
My Button
}
```
**Applied styles:**
- **When `type="primary"`:**
- Common: `display: inline-block`, `padding: 10px`
- Variant: `background: blue`, `color: white`
- **When `type="secondary"`:**
- Common: `display: inline-block`, `padding: 10px`
- Variant: `background: silver`, `color: black`
---
#### Multiple Variants
Allow multiple variant values (e.g., text styles):
```tsx
interface IButtonProps {
type: 'primary' | 'secondary'
text?: Array<'strong' | 'success' | 'error'>
}
const Div = styled.div(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()
})
```
Usage example:
```tsx
// Renders a primary button with both bold and red text styles
```
**Applied styles:**
- **Type "primary":** `background: blue`, `color: white`
- **Text variants:**
- `strong` adds `fontWeight: bold`
- `error` adds `color: red`
*Note: In case of conflicting styles (like two colors), the later applied style wins.*
---
#### Compound Variants
Compose multiple variants using private (internal) and public (external) props:
```tsx
interface IButtonProps {
// Private variants (used for composing public ones)
_background?: 'primary' | 'secondary' | 'success' | 'error'
_text?: Array<'dark' | 'light' | 'success' | 'error' | 'strong'>
// Public variant: the component's API
type: 'primary' | 'secondary' | 'success' | 'error'
children: string
}
const Div = styled.div(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' }
})
// Define compound variants mapping public 'type' to private ones.
.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:
```tsx
Primary button
Secondary button
Success button
Error 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 have a higher precedence than public ones, allowing you to override the default behavior for specific use cases.
```tsx
Error button
Error button with success background
```
**Applied styles:**
- The first button applies the default compound variant for `error`.
- The second button overrides the `_background` variant to `"success"`, so it receives `background: #eaff96` (as defined in the success mapping) while keeping the other error-related styles.
---
### 6. Conditional Blocks
Enable or skip blocks of styles based on a condition:
```tsx
const Div = styled.div(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 skipped.
---
### 7. Blocks Weight
Control the order of style application by assigning a weight to each block:
```ts
const Div = styled.div(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` style with weight 10 overrides any earlier conflicting `color` from `_text` if applied later.
---
### 8. Debugging
Log internal builder state to help diagnose complex style applications:
```tsx
const Div = styled.div(props => {
return buildVariants(props)
// Other style definitions…
.debug()
.end()
})
```
Or enable debugging conditionally:
```tsx
interface IButtonProps {
debug?: boolean
}
const Div = styled.div(props => {
return buildVariants(props)
// Other style definitions…
.debug(props.debug === true)
.end()
})
```
**Result:** Detailed logs in the console show which styles are applied and the builder's internal state.
---
## 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 empowers you to:
- **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.
Enjoy building maintainable, flexible UI components with Build-variants!