Constructor UI Components Library

Introduction

UI Components Library is a collection of React components that can be used to build UI for Constructor.io products.

Our Storybook Docs provide a comprehensive overview of each component, including its behavior, variations, and configuration options.

Requirements

• Node.js v22.18.0 (LTS Jod)
• React >=16.12.0
• React DOM >=16.12.0

Installation

npm i @constructor-io/constructorio-ui-components

Usage Patterns

Normal Usage

import { Button } from '@constructor-io/constructorio-ui-components';
import '@constructor-io/constructorio-ui-components/styles.css'

function App() {
  return <Button>Click me</Button>;
}

Render Other Components using asChild

import { Badge } from '@constructor-io/constructorio-ui-components';
import '@constructor-io/constructorio-ui-components/styles.css'

function App() {
  return (
    <Badge asChild variant="outline">
      <a href="#">
        A link that looks like a badge
      </a>
    </Badge>
  );
}

Component Overrides

import { Button } from '@constructor-io/constructorio-ui-components';
import '@constructor-io/constructorio-ui-components/styles.css'

function App() {
  return (
    <Button
      componentOverrides={{
        reactNode: <span>A span rendered in place of a button</span>
      }}
    >
      This will be overridden
    </Button>
  );
}

Passing Data Attributes

import { Button } from '@constructor-io/constructorio-ui-components';
import '@constructor-io/constructorio-ui-components/styles.css'

function App() {
  return <Button data-cnstrc-price={23.25}>Purchase</Button>;
}

Compound Components

import { ProductCard } from '@constructor-io/constructorio-ui-components';
import '@constructor-io/constructorio-ui-components/styles.css'

function App() {
  return (
    <ProductCard
      product={{
        id: 'highland-golf-pants',
        variationId: 'highland-golf-pants--navy',
        name: "Highland Golf Pants",
        imageUrl: 'https://example.com/pants.jpg',
        price: '799',
        rating: 4.8,
        reviewsCount: 203,
        description: 'Premium golf pants designed for comfort and performance on the course',
      }}
      className='overflow-hidden max-w-md'
    >
      <div className='grid grid-cols-2 gap-4 p-4'>
        <ProductCard.ImageSection />
        <div className='space-y-2'>
          <ProductCard.PriceSection />
          <ProductCard.TitleSection />
          <ProductCard.RatingSection />
        </div>
      </div>
      <ProductCard.Footer>
        <ProductCard.AddToCartButton />
      </ProductCard.Footer>
    </ProductCard>
  );
}

Tailwind CSS Prefix

This library uses Tailwind CSS v4 with a cio: prefix to avoid conflicts with your application's Tailwind classes. All utility classes and CSS variables are namespaced to ensure styles don't leak or collide.

Class Categories

The codebase uses two distinct class namespaces. They look similar but serve different purposes:

• cio-* (no colon) — plain CSS hooks / BEM identifiers attached to component roots and key sub-elements (e.g., cio-components, cio-badge, cio-product-card-image, cio-filter-visual-swatch). These are stable selectors used for styling overrides and tests; they are not Tailwind utilities and are never prefixed with cio:.
• cio:* (with colon) — Tailwind v4 utility classes scoped by the prefix(cio) import directive (e.g., cio:flex, cio:hover:bg-primary/90). The conventions in the rest of this section apply to these.

// Both kinds appear together on the same element:
<div className="cio-badge cio:inline-flex cio:items-center cio:gap-1.5">

Class Naming Convention

When adding or customizing Tailwind classes in this library, always use the cio: prefix:

// Correct
<div className="cio:flex cio:items-center cio:gap-2">

// Incorrect - will not work
<div className="flex items-center gap-2">

Variants and Modifiers

The prefix must come before any variants (hover, focus, responsive, etc.):

// Correct - prefix first, then variant, then utility
<button className="cio:bg-primary cio:hover:bg-primary/90 cio:disabled:opacity-50">

// Incorrect - variant before prefix
<button className="hover:cio:bg-primary/90 disabled:cio:opacity-50">

Responsive Breakpoints

// Correct
<div className="cio:p-2 cio:sm:p-4 cio:lg:p-6">

// Incorrect
<div className="cio:p-2 sm:cio:p-4 lg:cio:p-6">

Arbitrary Values and Selectors

// Correct
<div className="cio:w-[200px] cio:[&_svg]:size-4">

// Incorrect
<div className="[&_svg]:cio:size-4">

CSS Variables

CSS variables are prefixed with --cio-:

:root {
  --cio-primary: oklch(0.1969 0.0101 276.49);
  --cio-background: oklch(1 0 0);
  --cio-radius: 0.625rem;
}

Customizing Theme

You can override the default theme by setting the CSS variables in your application:

:root {
  --cio-primary: #your-brand-color;
  --cio-radius: 0.5rem;
}

Local Development

Development Scripts

npm ci                         # Install dependencies for local dev
npm run dev                    # Start a local dev server for Storybook
npm run lint                   # Run lint
npm run test                   # Run unit tests

Build scripts

npm run compile                # Compile the library, remove aliases, copy styles
npm run build-storybook        # Build Storybook
npm run serve-built-storybook  # Serve the built Storybook

Contributing

• Fork the repo & create a new branch.
• Run npm install to install dependencies.
• Submit a PR for review.

License

MIT © Constructor.io