mirror of
https://github.com/hunvreus/basecoat.git
synced 2026-11-12 13:18:22 +00:00
216 lines
7.4 KiB
Plaintext
216 lines
7.4 KiB
Plaintext
# 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.
|