Installation | Basecoat

Quickstart

The fastest way to get up and running is to load the CSS and all of the components' JavaScript using the CDN. Add the following to the <head> of your HTML file:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/basecoat-css@beta/dist/cdn.min.css">
<script src="https://cdn.jsdelivr.net/npm/basecoat-css@beta/dist/js/all.min.js" defer></script>
<script type="module">
  if (!("anchorName" in document.documentElement.style)) {
    import("https://cdn.jsdelivr.net/npm/basecoat-css@beta/dist/js/css-anchor-positioning.min.js");
  }
</script>

If you're not using all of the components requiring JavaScript (Dropdown Menu, Select, Sidebar, Tabs and Toast), follow the instructions below to only include the JavaScript files you actually need.

Install using the CDN

The easiest way to use Basecoat is use the CDN. First, add the CSS to the <head> of your HTML file:

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

Depending on the components you want to use, you may also need to add JavaScript files as instructed on the component's page. For example, for the Tabs component, you would add the following:

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

Install using NPM

Add Tailwind CSS

Basecoat uses Tailwind CSS. You need to install it in your project.

Follow the Tailwind CSS installation instructions to get started.
Add Basecoat

Add Basecoat to your Tailwind CSS file.
```
npm install basecoat-css
```
```
pnpm add basecoat-css
```
```
bun add basecoat-css
```
```
yarn add basecoat-css
```
Alternatively, you can directly copy the basecoat.css file into your project.

Import basecoat in your CSS

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

(Optional) Add JavaScript files

Some of the components may require some JavaScript, for example the Tabs component. Follow the instructions on the component's page.
That's it

You can now use any of the Basecoat classes in your project (e.g. btn, card, input, etc). Read the documentation about each component to get started (e.g. button, card, input, etc).

Some components (e.g. Select) require JavaScript code to work.

Components with JavaScript

Some components may require JavaScript code to work.

If a component requires JavaScript, the documentation page will provide instructions. There are 2 options to add the JavaScript code to your project:

CDN: you add the <script> tag provided on the component's page to the <head> of your HTML file.
Local file: you download the script as a separate file and include it in your project (or let the CLI do it for you). Make sure keep the defer attribute on the <script> tag when doing so.

A few things to keep in mind:

Most components (e.g. Button, Card, Input, etc) do not require any JavaScript at all to work.
Some of the JavaScript is optional. For example the Dropdown Menu component suggest to add the CSS anchor positioning polyfill to support older browser, as well as a dropdown-menu.js to improve accessiblity (WAI-ARIA) and usability (keyboard navigation).
Only a handful of components require JavaScript to work (e.g. Sidebar, Toast, ...).

If you're using Nunjucks or Jinja, you can use the CLI to install the CSS and macros for any of the complex components(e.g. Dialog). It will copy the JS and .html.jinja or .njk macros into your code.

For example, to add the Dialog component, run one of the following commands:

npx basecoat-cli add dialog

pnpm dlx basecoat-cli add dialog

bunx basecoat-cli add dialog

yarn dlx basecoat-cli add dialog

You will be asked to confirm the template engine and destination directory for the JavaScript and macros.

Use Nunjucks or Jinja macros

For more complex components, you can use Nunjucks or Jinja macros to help you generate the HTML and JavaScript code.

To install them, either copy them directly from the GitHub repository or use the CLI to do the work for you.

For example, here's how you could use the select() macro to generate the HTML and JavaScript code for a Select component:

{% call select() %}
<div role="group" aria-labelledby="fruit-options-label">
  <span id="fruit-options-label" role="heading">Fruits</span>
  <div role="option" data-value="apple">Apple</div>
  <div role="option" data-value="banana">Banana</div>
  <div role="option" data-value="blueberry">Blueberry</div>
  <div role="option" data-value="pineapple">Grapes</div>
  <div role="option" data-value="pineapple">Pineapple</div>
</div>
{% endcall %}

Make sure to include the JavaScript code before Alpine.js core JS file:

<script src="/assets/js/select.js" defer></script>
<script>
  document.addEventListener('alpine:init', () => {
    window.basecoat.registerSelect(Alpine);
  });
</script>
<script src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js" defer></script>

Theming

You can import any shadcn/ui compatible theme (e.g. tweakcn). For example:

Go to ui.shadcn.com/themes and select a theme.
Click "Copy code" and save the theme variables in a file (e.g. theme.css).

Import the theme in your CSS file:

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

About shadcn/ui theming

Customization

You can override default styles using Tailwind:

<button class="btn font-normal ">Click me</button>

You can also extend or override the existing styles in your own Tailwind files:

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

More importantly, you can use the theme variables to customize many aspects of the components (colors, fonts, sizes, etc).

If you want to make more drastic changes, you can copy the basecoat.css file into your project and make your changes there.