# 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

<Steps>
  <Step title="Add the stylesheet">

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

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/basecoat-css@1.0.0-beta.6/dist/basecoat.cdn.min.css" />
```

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

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/basecoat-css@1.0.0-beta.6/dist/basecoat-maia.cdn.min.css" />
```

  </Step>
  <Step title="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.

```html
<script src="https://cdn.jsdelivr.net/npm/basecoat-css@1.0.0-beta.6/dist/js/all.min.js" defer></script>
```

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

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

  </Step>
  <Step title="Use the markup">

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

  </Step>
</Steps>

<Callout title="Icons are not bundled" icon="info">
  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](/customization#icons).
</Callout>

### 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 JavaScript components. |
| `dist/js/basecoat.min.js` | Runtime only. Load once before individual component scripts. |
| `dist/js/{component}.min.js` | Individual JavaScript component file. |

## NPM

<Steps>
  <Step title="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](https://tailwindcss.com/docs/installation).

  </Step>
  <Step title="Install Basecoat">

<CodeGroup defaultTab="npm">
  <Code title="npm" lang="bash">{`npm install basecoat-css`}</Code>
  <Code title="pnpm" lang="bash">{`pnpm add basecoat-css`}</Code>
  <Code title="bun" lang="bash">{`bun add basecoat-css`}</Code>
  <Code title="yarn" lang="bash">{`yarn add basecoat-css`}</Code>
</CodeGroup>

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

  </Step>
  <Step title="Add CSS">

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

```html
<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`.

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

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

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

Or import a named style bundle.

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

<Callout type="warning" title="Stylesheet order matters" icon="triangle-alert">
  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.
</Callout>

  </Step>
  <Step title="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.

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

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

```html
<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:

```js
import "basecoat-css/all";
```

Or import the runtime once, then individual components.

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

  </Step>
</Steps>

### 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. |

### JavaScript imports

| Import | Description |
| --- | --- |
| `basecoat-css/all` | All JavaScript components. |
| `basecoat-css/basecoat` | Runtime only. Import once before individual component scripts. |
| `basecoat-css/combobox` | Combobox controller. |
| `basecoat-css/command` | Command 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:

- [Combobox](/components/combobox)
- [Command](/components/command)
- [Dropdown Menu](/components/dropdown-menu)
- [Popover](/components/popover)
- [Select](/components/select)
- [Sidebar](/components/sidebar)
- [Slider](/components/slider)
- [Tabs](/components/tabs)
- [Toast](/components/toast)

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

## 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.

```css
@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.