Installation

Chassis CSS, Chassis Icons and Chassis Tokens are published to npm as @chassis-ui/css, @chassis-ui/icons and @chassis-ui/tokens. This page adds them to a web project. Chassis CSS and Chassis Icons document each package in full.

Requirements

• Node.js 22 or later. @chassis-ui/css and @chassis-ui/tokens require it in their engines field.
• A package manager: pnpm, npm or yarn.

Install the packages

Install Chassis CSS and Chassis Icons:

# pnpm
pnpm add @chassis-ui/css @chassis-ui/icons

# npm
npm install @chassis-ui/css @chassis-ui/icons

# yarn
yarn add @chassis-ui/css @chassis-ui/icons

The JavaScript plugins of Chassis CSS use two peer dependencies: @floating-ui/dom for menus, popovers and tooltips, and vanilla-calendar-pro for the datepicker. npm 7 and later installs them automatically. To install them yourself:

pnpm add @floating-ui/dom vanilla-calendar-pro

Two more peer dependencies are optional: postcss-prefix-custom-properties, for the PostCSS step of a Sass build, and tailwindcss, for the Tailwind CSS entry.

You need @chassis-ui/tokens only when you compile from Sass. The compiled CSS already contains the default tokens.

Use the compiled CSS

dist/css/chassis.min.css holds all of Chassis CSS, compiled with the default tokens and the default settings. Link it in your HTML:

<link rel="stylesheet" href="node_modules/@chassis-ui/css/dist/css/chassis.min.css">

Or import it in a project with a bundler:

import '@chassis-ui/css/dist/css/chassis.min.css'

dist/css/ also has chassis-grid.css, chassis-reboot.css and chassis-utilities.css, the grid, the reset and the utility classes on their own, each with a minified build.

Add the JavaScript

Interactive components, such as dialogs, menus and tooltips, need the JavaScript. The builds are ES modules. chassis.bundle.min.js includes both peer dependencies:

<script type="module" src="node_modules/@chassis-ui/css/dist/js/chassis.bundle.min.js"></script>

chassis.min.js leaves them out, and expects them to be resolved separately.

Components with a data attribute API, such as data-cx-toggle="tooltip", initialize themselves. To control a component from code, import its plugin:

import { Dialog } from '@chassis-ui/css'

Dialog.getOrCreateInstance('#welcome-dialog').show()

The JavaScript guide of Chassis CSS covers the data attributes, the programmatic API, the events and the full list of plugins.

Add the icons

@chassis-ui/icons holds the icon font and the SVG sprite in its icons/ folder, and each icon as an SVG file in svgs/.

To use the icon font, link its stylesheet and give an element the cx- class of the icon. The icon class comes from Chassis CSS:

<link rel="stylesheet" href="node_modules/@chassis-ui/icons/icons/chassis-icons.min.css">

<span class="icon cx-rocket-solid" aria-hidden="true"></span>

The stylesheet loads chassis-icons.woff2 and chassis-icons.woff from its own folder. When you copy it into your project, copy the font files next to it.

To use the SVG sprite, reference an icon by its name:

<svg class="icon" width="24" height="24" aria-hidden="true">
  <use href="node_modules/@chassis-ui/icons/icons/chassis-icons.svg#rocket-solid"></use>
</svg>

Serve the sprite from the same origin as the page. <use> does not load a sprite from another domain.

Compile from Sass

Compile Chassis CSS from its Sass source to change its settings or use other tokens. Install the tokens and Dart Sass:

pnpm add @chassis-ui/tokens
pnpm add -D sass

Chassis CSS uses the Sass module system. Configure the settings with @use ... with, before the main import:

// scss/styles.scss
@use "@chassis-ui/css/scss/config" with (
  $enable-dark-mode: false
);
@use "@chassis-ui/css/scss/chassis";

Sass needs two load paths: node_modules, and the scss/vendor folder of @chassis-ui/css. That folder holds _chassis-tokens.scss, which forwards the default tokens from @chassis-ui/tokens. To use other tokens, put a _chassis-tokens.scss of your own in a folder that comes before it on the load path.

pnpm exec sass \
  --load-path=node_modules/@chassis-ui/css/scss/vendor \
  --load-path=node_modules \
  scss/styles.scss dist/styles.css

The guides of Chassis CSS set the same load paths in Vite, Webpack and Parcel. Sass customization covers the settings and the token sources.

Add the prefix to custom properties

Sass writes the custom properties without a prefix, such as --primary. The compiled CSS in dist/css/ has the --cx- prefix, which a PostCSS plugin of Chassis CSS adds. Install PostCSS and the plugin's peer dependency:

pnpm add -D postcss-cli postcss-prefix-custom-properties

Add a PostCSS configuration next to package.json:

// postcss.config.mjs
import { chassisPrefix } from '@chassis-ui/css/postcss'

export default {
  plugins: [chassisPrefix()]
}

Run it after every Sass compile:

pnpm exec postcss dist/styles.css -o dist/styles.css

The prefix is optional unless you use the Tailwind CSS entry. The installation guide of Chassis CSS explains when to use it and how to choose another prefix.

Try it from a CDN

To try Chassis CSS without installing anything, load it from jsDelivr, as the quick start of Chassis CSS does. These links are for version 0.11.1:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@chassis-ui/css@0.11.1/dist/css/chassis.min.css" integrity="sha384-ZSWES0mK9toeDOpb2Zgj4gf3tw53P4CsZoLAQIqPNnFywuSWObV3BO4onoE/9obh" crossorigin="anonymous">

<script type="module" src="https://cdn.jsdelivr.net/npm/@chassis-ui/css@0.11.1/dist/js/chassis.bundle.min.js" integrity="sha384-quX9M/QyJwijGU7oGLfD9iVFBbAdSZrIUmMxdtBRperWN5QfPzOsGHtamgwTWBOQ" crossorigin="anonymous"></script>

The CDN build uses the default tokens and settings. For your own tokens or settings, install the packages and compile from Sass.

Chassis React

Chassis React uses the stylesheet of Chassis CSS. Install both, with React and React DOM 18 or later in your project:

pnpm add @chassis-ui/react @chassis-ui/css

The Chassis React repository explains how to import the styles and the components.

A working example

The vanilla HTML example is a plain HTML page that uses Chassis CSS and Chassis Icons from npm, with the fonts and the logo of Chassis Assets. Use it as a reference for the files a page needs.

The example is one repository that is deployed as a website per brand: the same page with the design tokens, the fonts and the logo of each brand. The examples page links every site.

Continue with Next steps.