Installation

Basecoat can be used from a CDN or installed with npm. Use the CDN for simple static pages and prototypes. Use npm when your project already has a Tailwind CSS build step.

CDN

Add the stylesheet

Use the default bundled stylesheet. It is an alias for the Vega style bundle.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/basecoat-css@1.0.2/dist/basecoat.cdn.min.css" />

You can also use one of the named style bundles: vega, nova, maia, lyra, mira, luma, sera, or rhea.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/basecoat-css@1.0.2/dist/basecoat-maia.cdn.min.css" />

Add JavaScript when needed

Most components are CSS-only. Interactive components need JavaScript. Use the all-in-one bundle when file size is not a concern.

<script src="https://cdn.jsdelivr.net/npm/basecoat-css@1.0.2/dist/js/all.min.js" defer></script>

Or load the Basecoat runtime once, then only the component scripts you use.

<script src="https://cdn.jsdelivr.net/npm/basecoat-css@1.0.2/dist/js/basecoat.min.js" defer></script>
<script src="https://cdn.jsdelivr.net/npm/basecoat-css@1.0.2/dist/js/dropdown-menu.min.js" defer></script>
<script src="https://cdn.jsdelivr.net/npm/basecoat-css@1.0.2/dist/js/select.min.js" defer></script>

Use the markup

<button class="btn">Button</button>
<div class="card">
  <header>
    <h3>Card title</h3>
    <p>Card description.</p>
  </header>
  <section>Card content.</section>
</div>

Icons are not bundled

Basecoat examples use inline Lucide SVGs, but Basecoat does not ship an icon package. Copy SVGs into your markup or install your preferred icon library. See Customization > Icons.

CDN files

File	Description
`dist/basecoat.cdn.min.css`	Default standalone CDN stylesheet. Alias for the Vega style.
`dist/basecoat-{style}.cdn.min.css`	Standalone CDN stylesheet for `vega`, `nova`, `maia`, `lyra`, `mira`, `luma`, `sera`, or `rhea`.
`dist/basecoat-base.cdn.min.css`	Base tokens, utilities, and component structure without a style pack.
`dist/basecoat-compat.cdn.min.css`	Optional pre-1.0 compatibility aliases. Load after Basecoat.
`dist/js/all.min.js`	All auto-initialized JavaScript components except Chart.
`dist/js/basecoat.min.js`	Runtime only. Load once before individual component scripts.
`dist/js/{component}.min.js`	Individual JavaScript component file.

NPM

Install Tailwind CSS

Basecoat is authored for Tailwind CSS. Install Tailwind first if your project does not already use it.

Follow the Tailwind CSS installation guide.

Install Basecoat

npm install basecoat-css

pnpm add basecoat-css

bun add basecoat-css

yarn add basecoat-css

If you are not using a bundler, copy or serve the files you need from node_modules/basecoat-css/dist.

Add CSS

Include one Basecoat stylesheet after your Tailwind CSS. The default stylesheet is an alias for the Vega style bundle.

<link rel="stylesheet" href="/assets/basecoat.css" />

You can also use one of the named style bundles: vega, nova, maia, lyra, mira, luma, sera, or rhea.

<link rel="stylesheet" href="/assets/basecoat-maia.css" />

If your build tool supports CSS package imports, import Tailwind and then one Basecoat bundle.

@import "tailwindcss";
@import "basecoat-css";

Or import a named style bundle.

@import "tailwindcss";
@import "basecoat-css/maia";

Stylesheet order matters

Load Basecoat after any stylesheet that includes Tailwind base/preflight. Loading another full Tailwind build after Basecoat can reset borders, inputs, and other component defaults.

Add JavaScript when needed

Most components are CSS-only. Interactive components need JavaScript. Include the all-in-one script when file size is not a concern.

<script src="/assets/js/all.min.js" defer></script>

Or include the Basecoat runtime once, then only the component scripts you use.

<script src="/assets/js/basecoat.min.js" defer></script>
<script src="/assets/js/dropdown-menu.min.js" defer></script>
<script src="/assets/js/select.min.js" defer></script>

If your build tool supports JavaScript package imports, use the all-in-one import:

import "basecoat-css/all";

Or import the runtime once, then individual components.

import "basecoat-css/basecoat";
import "basecoat-css/dropdown-menu";
import "basecoat-css/select";

Templates

Basecoat ships optional Nunjucks and Jinja templates with basecoat-css.

If you previously used basecoat-cli, install basecoat-css instead and copy the template files from the package.

cp -R node_modules/basecoat-css/templates/nunjucks ./templates/basecoat

cp -R node_modules/basecoat-css/templates/jinja ./templates/basecoat

See Templates for the available macros and arguments.

CSS imports

Import	Description
`basecoat-css`	Default full stylesheet. Alias for `basecoat-css/vega`.
`basecoat-css/{style}`	Full stylesheet for `vega`, `nova`, `maia`, `lyra`, `mira`, `luma`, `sera`, or `rhea`.
`basecoat-css/base`	Base tokens, utilities, and component structure without a style pack. Use this before a custom style.
`basecoat-css/components`	All component structure without a style pack.
`basecoat-css/components/button`	Individual component CSS. Replace `button` with any component file.
`basecoat-css/styles/maia`	Individual style-pack CSS. Use with `basecoat-css/base` or `basecoat-css/components`.
`basecoat-css/all.css`	Full default stylesheet plus all style-pack CSS. Use only when you need every style pack available at runtime.
`basecoat-css/compat`	Optional pre-1.0 compatibility aliases. Load after Basecoat.

Template files

Path	Description
`node_modules/basecoat-css/templates/nunjucks`	Nunjucks templates.
`node_modules/basecoat-css/templates/jinja`	Jinja templates.

JavaScript imports

Import	Description
`basecoat-css/all`	All auto-initialized JavaScript components except Chart.
`basecoat-css/basecoat`	Runtime only. Import once before individual component scripts.
`basecoat-css/chart`	Chart helper. Load Chart.js separately.
`basecoat-css/combobox`	Combobox controller.
`basecoat-css/command`	Command controller.
`basecoat-css/drawer`	Drawer controller.
`basecoat-css/dropdown-menu`	Dropdown Menu controller.
`basecoat-css/popover`	Popover controller.
`basecoat-css/range`	Slider/range controller.
`basecoat-css/select`	Select controller.
`basecoat-css/sidebar`	Sidebar controller.
`basecoat-css/tabs`	Tabs controller.
`basecoat-css/toast`	Toast controller.

JavaScript components

These components need JavaScript for behavior:

Chart uses a separate helper and is not included in basecoat-css/all.

Each component page shows the minimal scripts or imports required for that component.

JavaScript lifecycle

Basecoat initializes registered components on page load and when new DOM is inserted.

Use window.basecoat.initAll() after manually inserting HTML that contains Basecoat components. It only initializes components that are not already initialized.

Use window.basecoat.initAll({ force: true }) when a framework or navigation library restores previously initialized DOM from a cache, such as an HTMX history restore. Force mode destroys existing component instances before reinitializing them, so it also resets transient state such as open menus, focus state, and active interactions.

Compatibility

Basecoat 1.0 introduces new style packs and a smaller public API based on root classes plus semantic HTML and documented attributes. If you need pre-1.0 class aliases while migrating, load the compatibility stylesheet after your Basecoat stylesheet.

@import "tailwindcss";
@import "basecoat-css";
@import "basecoat-css/compat";

The compatibility stylesheet is intended for the default Basecoat style. It is not a separate style pack.