basecoat/docs/src/installation.njk

---
layout: layouts/page.njk
title: Installation
description: How to install and use Basecoat in your app.
toc:
  - label: Installing the CSS
    id: install-css
    children:
      - label: Add Tailwind CSS
        id: install-css
      - label: Add Basecoat
        id: install-css-basecoat
      - label: Import basecoat in your CSS
        id: install-css-import
      - label: That's it
        id: install-css-done
  - label: Components with Javascript
    id: install-js
  - label: Use the CLI
    id: install-cli
  - label: Use Nunjucks or Jinja macros
    id: install-macros
  - label: Theming
    id: install-theming
---

{% from "macros/code_block.njk" import code_block %}

<h2 id="install-css">Install the CSS</h2>

<div class="alert my-6">
  {% lucide "circle-alert" %}
  <h2>If you don't want to use npm, you can follow the <a href="#install-manual" class="underline underline-offset-4">manual installation instructions</a>.</h2>
</div>

<ol class="[&>h3]:step steps mb-12 md:ml-4 md:border-l md:pl-8">
  <li class="step">
    <h4 class="mb-4 scroll-m-20 font-semibold tracking-tight" id="install-css-tailwind"><a href="#install-css-tailwind">Add Tailwind CSS</a></h4>
    <div class="prose">
      <p>Basecoat uses Tailwind CSS. You need to install it in your project.</p>
      <p><a href="https://tailwindcss.com/docs/installation" target="_blank">Follow the Tailwind CSS installation instructions to get started.</a></p>
    </div>
  </li>
  <li class="step mt-8">
    <h3 class="mb-4 scroll-m-20 font-semibold tracking-tight" id="install-css-basecoat"><a href="#install-css-basecoat">Add Basecoat</a></h3>
    <div class="prose">
      <p>Add Basecoat to your Tailwind CSS file.</p>
    </div>
    {% set code %}npm install hunvreus/basecoat{% endset %}
    {{ code_block(code, "bash") }}
    <div class="prose">
      <p>Alternatively, you can directly <a href="https://github.com/hunvreus/basecoat/blob/main/src/css/basecoat.css" target="_blank">copy the <code>basecoat.css</code> file</a> into your project.</p>
    </div>
  </li>
  <li class="step mt-8">
    <h3 class="mb-4 scroll-m-20 font-semibold tracking-tight" id="install-css-import"><a href="#install-css-import">Import basecoat in your CSS</a></h3>
    {% set code %}@import "tailwindcss";
@import "basecoat";{% endset %}
    {{ code_block(code, "css") }}
  </li>
  <li class="step mt-8">
    <h3 class="mb-4 scroll-m-20 font-semibold tracking-tight" id="install-css-done"><a href="#install-css-done">That's it</a></h3>
    <div class="prose">
      <p>You can now use any of the Basecoat classes in your project (e.g. <code>btn</code>, <code>card</code>, <code>input</code>, etc). Read the documentation about each component to get started (e.g. <a href="/components/button">button</a>, <a href="/components/card">card</a>, <a href="/components/input">input</a>, etc).</p>
      <p>Some components (e.g. <a href="/components/select">Select</a>) require <a href="#install-js">Javascript code to work</a>.</p>
    </div>
  </li>
</ol>

<h2 id="install-js"><a href="#install-js">Components with Javascript</a></h2>

<div class="prose">
  <p><b>Some components require Javascript code to work.</b></p>
  <p>The documentation provides Alpine.js code snippets to cover that. <a href="https://alpinejs.dev/docs/installation" target="_blank">Make sure to install Alpine.js if you decide to use them.</a></p>
  <p>For simple components like <a href="/components/accordion">Accordion</a> or <a href="/components/slider">Slider</a>, you will notice some inline Alpine.js code that you can just copy along with the rest of the HTML.</p>
  <p>For more complex components (<a href="/components/dialog">Dialog</a>, <a href="/components/dropdown-menu">Dropdown Menu</a>, <a href="/components/popover">Popover</a>, <a href="/components/select">Select</a>, <a href="/components/tabs">Tabs</a> and <a href="/components/tooltip">Toast</a>), you have one of 2 options:
  <ul>
    <li>Copy the Javascript snippet provided in the documentation page into your project.</li>
    <li>
      <p><a href="https://github.com/hunvreus/basecoat/tree/main/src/js" target="_blank">Download the script as a separate file</a> and include it in your project (<a href="#install-cli">or let the CLI do it for you</a>). <b>If you use this approach, make sure to load the file before the Alpine.js core JS file and register the component on the <code>alpine:init</code> event.</b> For example:</p>
      {% set code %}<script src="/assets/js/dialog.js" defer></script>
<script>
  document.addEventListener('alpine:init', () => {
    window.basecoat.registerDialog(Alpine);
  });
</script>
<script src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js" defer></script>{% endset %}
      {{ code_block(code, "html") }}
    </li>
  </ul>
  <p>You are also welcome to write your own Javascript.</p>
  <p>All of the components try and implement WAI-ARIA standards to make them accessible.</p>
</div>

<h2 id="install-cli"><a href="#install-cli">Use the CLI</a></h2>

<div class="prose">
  <p>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. <a href="/components/dialog">Dialog</a>). It will copy the JS and `<code>.html.jinja</code> or <code>.njk</code> macros into your code.</p>
  <p>For example, to add the Dialog component, run:</p>
  {% set code %}npx basecoatui add dialog{% endset %}
  {{ code_block(code, "bash") }}
  <p>You will be asked to confirm the template engine and destination directory for the Javascript and macros.</p>
</div>

<h2 id="install-macros"><a href="#install-macros">Use Nunjucks or Jinja macros</a></h2>

<div class="prose">
  <p>For more complex components, you can use <a href="https://mozilla.github.io/nunjucks/" target="_blank">Nunjucks</a> or <a href="https://jinja.palletsprojects.com" target="_blank">Jinja</a> macros to help you generate the HTML and Javascript code.</p>
  <p>To install them, either <a href="https://github.com/hunvreus/basecoat/tree/main/src" target="_blank">copy them directly from the GitHub repository</a> or use <a href="#install-cli">the CLI</a> to do the work for you.</p>
  <p>For example, here's how you could use the <code>select()</code> macro to generate the HTML and Javascript code for a <a href="/components/select">Select</a> component:</p>
  {% set code %}{% raw %}{% 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 %}{% endraw %}{% endset %}
  {{ code_block(code, "jinja") }}
  <p>Make sure to include the Javascript code <b>before</b> Alpine.js core JS file:</p>
  {% set code %}<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>{% endset %}
{{ code_block(code, "jinja") }}
</div>

<h2 id="install-theming"><a href="#install-theming">Theming</a></h2>

<div class="prose">
  <p>You can import any <a href="https://shadcn-ui.com" target="_blank">shadcn/ui</a> compatible theme (e.g. <a href="https://tweakcn.com" target="_blank">tweakcn</a>). For example:</p>
  <ul>
    <li>Go to <a href="https://ui.shadcn.com/themes" target="_blank">ui.shadcn.com/themes</a> and select a theme.</li>
    <li>Click "Copy code" and save the theme variables in a file (e.g. <code>theme.css</code>).</li>
    <li>
      Import the theme in your CSS file:
      {% set code %}@import "tailwindcss";
@import "basecoat";
@import "theme.css";{% endset %}
      {{ code_block(code, "css") }}
    </li>
  </ul>
  <p><a href="https://ui.shadcn.com/docs/theming" target="_blank">Read more about theming on the shadcn/ui website.</a></p>
</div>