DOCSEARCHbyAlgolia
Submit Docs

Basecoat Documentation

repository·main·Indexed 26 days ago

https://github.com/hunvreus/basecoat

A framework-agnostic implementation of the shadcn/ui design system using Tailwind CSS, vanilla HTML, CSS, and JS. Basecoat provides semantic components without requiring React or Radix, featuring a global window.basecoat object for state management and various CSS entrypoints including style packs like Vega and Nova.

Tokens
56.6K
Snippets
153
Records
239
Agent score
88%

What's inside Basecoat

  1. Overview of Basecoat

    main

    Basecoat is a framework-agnostic UI library designed to bring the design system and component experience of shadcn/ui to traditional web stacks without requiring React. It is built for developers using plain HTML, Flask, Rails, Laravel, Django, or any other stack.

    Key characteristics:

    • Lightweight: Uses only CSS and minimal vanilla JavaScript for interactivity.
    • Easy to use: Components are applied via simple classes like btn, field, or card.
    • Accessible: Follows accessibility best practices.
    • Tailwind Integrated: Respects your Tailwind configuration and is dark mode ready.
    • Themable: Fully compatible with shadcn/ui themes.
    • Readable: Avoids 'class soup' by using semantic component classes instead of long strings of utility classes.

  2. Create an Avatar group

    main

    To group multiple avatars with an overlapping effect, wrap them in a container with the avatar-group class.

    Group features:

    • Count Indicator: Add a <span data-count>+N</span> as the last child of the group to show how many additional avatars are hidden.
    • Icon Indicator: Use a <span data-count> containing an icon (like a plus sign) instead of text.
    <div class="avatar-group">
  <span class="avatar"><img src="..." /><span class="CN"></span></span>
  <span class="avatar"><img src="..." /><span class="LR"></span></span>
  <span data-count>+3</span>
</div>

  3. Support RTL (Right-to-Left) in Dialogs

    main

    The Dialog component uses CSS logical properties for positioning and close button placement. To enable RTL support, set the dir="rtl" attribute on the <dialog> element or any of its parent elements.

    <div dir="rtl">
  <button type="button" onclick="document.getElementById('dialog-rtl').showModal()" class="btn" data-variant="outline">فتح الحوار</button>
  <dialog id="dialog-rtl" class="dialog" ...>
    <!-- RTL content -->
  </dialog>
</div>

  5. Implement a Theme Switcher with Basecoat

    main

    To implement a theme switcher, follow these steps to include the necessary CSS, JavaScript, and prevent theme flashing.

    1. Include CSS

    Import Tailwind and a Basecoat style bundle (e.g., vega.css), or import the base CSS, specific component CSS (like button.css and tooltip.css), and a style pack.

    2. Include JavaScript

    Serve the full Basecoat JavaScript bundle or the Basecoat runtime.

    3. Avoid the initial flash

    Add the following inline script before loading your styles to apply the stored theme mode before the page renders.

    4. Add the switcher HTML

    Use a button with the onclick="window.basecoat.theme.toggle()" attribute. The switcher component relies on Button and Tooltip component CSS.

    <!-- 1. CSS Example -->
@import "tailwindcss";
@import "basecoat-css/vega.css";

<!-- 2. JS Example -->
<script src="/assets/js/all.min.js" defer></script>

<!-- 3. Prevent Flash Example -->
<script>
  (() => {
    try {
      const stored = localStorage.getItem("themeMode");
      if (stored ? stored === "dark" : matchMedia("(prefers-color-scheme: dark)").matches) {
        document.documentElement.classList.add("dark");
      }
    } catch (_) {}
  })();
</script>

<!-- 4. HTML Example -->
<button type="button" aria-label="Toggle dark mode" data-tooltip="Toggle dark mode" data-side="bottom" onclick="window.basecoat.theme.toggle()" class="btn size-8" data-variant="outline" data-size="icon">
  <span class="hidden dark:block"><svg>...</svg></span>
  <span class="block dark:hidden"><svg>...</svg></span>
</button>

  6. Implement the Slider component

    main

    The Slider component is built on top of the native HTML <input type="range"> element. To use it, you must include the necessary CSS and JavaScript to style the input and ensure the filled track stays in sync with the input value.

    1. Include CSS

    You can either import a full style bundle or import specific pieces. Note that the Slider requires the range.css component styles.

    Option A: Full style bundle

    @import "tailwindcss";
@import "basecoat-css/vega.css";

    Option B: Granular imports

    @import "tailwindcss";
@import "basecoat-css/base.css";
@import "basecoat-css/components/range.css";
@import "basecoat-css/styles/vega.css";

    2. Include JavaScript

    You must serve the Basecoat runtime and the specific Slider (range) script to enable track synchronization.

    Option A: Full bundle

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

    Option B: Granular scripts

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

    3. Add HTML

    <input type="range" class="input w-full" min="0" max="100" value="50" />

  7. Set up the Tabs component

    main

    To use the Tabs component, you must include the necessary CSS and JavaScript.

    1. Include CSS

    You can import the full Basecoat style bundle or just the specific component styles:

    Full bundle:

    @import "tailwindcss";
@import "basecoat-css/vega.css";

    Component-specific:

    @import "tailwindcss";
@import "basecoat-css/base.css";
@import "basecoat-css/components/tabs.css";
@import "basecoat-css/styles/vega.css";

    2. Include JavaScript

    Serve the full Basecoat bundle or the specific runtime and Tabs script:

    Full bundle:

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

    Specific scripts:

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

  8. Implement Pagination with Basecoat

    main

    Basecoat does not provide a dedicated pagination component. Instead, you implement pagination by using Tailwind CSS utility classes combined with Basecoat's btn component classes for links and controls.

    To implement pagination, use a <nav> element with role="navigation" and an aria-label="pagination". Inside, use an unordered list (<ul>) with flex-row and items-center to layout the page links. Use the btn class with various data-variant and data-size attributes to style the individual items.

    <nav role="navigation" aria-label="pagination" class="mx-auto flex w-full justify-center">
  <ul class="flex flex-row items-center gap-1">
    <li>
      <a href="#" class="btn" data-variant="ghost">
        <!-- Icon here -->
        Previous
      </a>
    </li>
    <li><a href="#" class="btn" data-variant="ghost" data-size="icon">1</a></li>
    <li><a href="#" class="btn" data-variant="outline" data-size="icon">2</a></li>
    <li><a href="#" class="btn" data-variant="ghost" data-size="icon">3</a></li>
    <li>
      <a href="#" class="btn" data-variant="ghost">
        Next
        <!-- Icon here -->
      </a>
    </li>
  </ul>
</nav>

  9. Configure CSS for Pagination

    main

    Pagination relies on the Button component CSS. You must import Tailwind and either a full Basecoat style bundle or the specific required files.

    Option 1: Full Style Bundle Import Tailwind and a complete style pack (e.g., vega.css).

    @import "tailwindcss";
@import "basecoat-css/vega.css";

    Option 2: Granular Imports Import Tailwind, the base CSS, the button component CSS, and a style pack.

    @import "tailwindcss";
@import "basecoat-css/base.css";
@import "basecoat-css/components/button.css";
@import "basecoat-css/styles/vega.css";

  10. Setup the Card component

    main

    To use the Card component, you must include Tailwind CSS and a Basecoat style bundle. You can import a full style bundle or import only the necessary base and component CSS files.

    Option 1: Full style bundle

    @import "tailwindcss";
@import "basecoat-css/vega.css";

    Option 2: Granular imports

    @import "tailwindcss";
@import "basecoat-css/base.css";
@import "basecoat-css/components/card.css";
@import "basecoat-css/styles/vega.css";

  11. Migrate to Basecoat 1.0 compatibility mode

    main

    Basecoat 1.0 uses a new style pack system. If you need pre-1.0 class aliases during migration, load the basecoat-css/compat stylesheet after your main Basecoat stylesheet. Note that compatibility aliases are only available for the default Basecoat style, not other style packs.

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

  12. Include Alert component CSS

    main

    To use the Alert component, you must include Tailwind CSS and either a full Basecoat style bundle or the specific component and base CSS files.

    Option 1: Full style bundle

    @import "tailwindcss";
@import "basecoat-css/vega.css";

    Option 2: Granular imports

    @import "tailwindcss";
@import "basecoat-css/base.css";
@import "basecoat-css/components/alert.css";
@import "basecoat-css/styles/vega.css";