Customization

Configure icons, themes, fonts, and style overrides.

Icons

Basecoat uses Lucide icons. You have three options:

  • Copy SVG code: Visit lucide.dev/icons, click any icon to copy the SVG, and paste it directly in your HTML. Best for simple projects or occasional icon usage.
  • Install lucide: Follow the installation guide to install the lucide package and dynamically render icons. Best for projects that need many icons or want tree-shaking.
  • Use framework packages: Browse framework-specific packages (React, Vue, Angular, etc.) for component-based icon usage. Best if you're using a supported framework.
Browse icons Installation guide Packages

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/sera";
@import "./theme.css";
About shadcn/ui theming

Fonts

Basecoat does not ship web fonts by default. The Basecoat docs site uses the same font choices as the current shadcn/ui site: Geist Sans for sans and heading text, and Geist Mono for monospace text.

To use the same setup, load the fonts and override the font tokens after importing Basecoat:

@import "tailwindcss";
@import "basecoat-css/sera";
@import "@fontsource/geist-sans/400.css";
@import "@fontsource/geist-sans/500.css";
@import "@fontsource/geist-sans/600.css";
@import "@fontsource/geist-sans/700.css";
@import "@fontsource/geist-mono/400.css";
@import "@fontsource/geist-mono/500.css";
@import "@fontsource/geist-mono/600.css";
@import "@fontsource/geist-mono/700.css";

:root {
  --font-sans: "Geist Sans", ui-sans-serif, system-ui, sans-serif;
  --font-heading: "Geist Sans", ui-sans-serif, system-ui, sans-serif;
  --font-mono: "Geist Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
}

Keep font overrides in a small CSS file imported after Basecoat. This makes fonts a project-level customization instead of a Basecoat package default.

Custom styles

Basecoat style packs combine shared Basecoat structure with visual rules for each component. If you want to write a full custom style, import the styleless Basecoat base and then your own style file.

@import "tailwindcss";
@import "basecoat-css/base";
@import "./style-acme.css";

basecoat-css/base includes Basecoat tokens, semantic utilities, and component structure, but no Vega/Nova/Maia/etc. visual style pack. Your style file is responsible for component visuals such as colors, radius, shadows, focus rings, spacing, and variant treatment.

The practical way to start is to copy one existing style pack, rename it, and edit from there. The style files live in src/css/styles/ and are also published under basecoat-css/styles/*.

@import "basecoat-css/base";
@import "./style-acme.css";

/* style-acme.css can start as a copy of basecoat-css/styles/nova. */

Do not load a full Basecoat style bundle and then override it wholesale. For example, avoid importing basecoat-css/nova before your custom style. That loads Nova component visuals and forces your file to undo them. Use basecoat-css/base instead.

Style overrides

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/sera";
@import "./custom.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.