Getting Started

Installation

WebBlocks UI has no build step and zero dependencies. Pick the method that fits your project.

CDN (recommended for most projects)

The fastest way to get started. Files are served via jsDelivr from GitHub releases.

<!-- Add to <head> -->
<link rel="stylesheet"
      href="https://cdn.jsdelivr.net/gh/fklavyenet/webblocks-ui@v2.3.5/dist/webblocks-ui.css">

<!-- Add before </body> -->
<script src="https://cdn.jsdelivr.net/gh/fklavyenet/webblocks-ui@v2.3.5/dist/webblocks-ui.js"></script>

Download & Self-host

Download the built files and serve them from your own server — no internet dependency, no CDN.

Option A — Download latest release (ZIP)

Go to github.com/fklavyenet/webblocks-ui/releases/latest
Under Assets, click Source code (zip) to download
Extract the ZIP, copy the dist/ folder into your project
Reference the files with a relative path:

<link rel="stylesheet" href="/assets/webblocks-ui.css">
<script src="/assets/webblocks-ui.js"></script>

Option B — Clone with git

Clone the full repository and use the dist/ files directly. Pull to update to the latest version at any time.

# Clone the repository
git clone https://github.com/fklavyenet/webblocks-ui.git

# Or clone a specific tagged version
git clone --branch v2.2.5 --depth 1 https://github.com/fklavyenet/webblocks-ui.git

# Files you need are in dist/
#   dist/webblocks-ui.css
#   dist/webblocks-ui.js
#   dist/webblocks-icons.svg   (for SVG sprite icons)
#   dist/webblocks-icons.css   (for <i> tag icons, opt-in)

Option C — Direct file download

Download individual files directly from the GitHub repository without cloning:

# Download built files directly (curl)
curl -O https://raw.githubusercontent.com/fklavyenet/webblocks-ui/v2.2.5/dist/webblocks-ui.css
curl -O https://raw.githubusercontent.com/fklavyenet/webblocks-ui/v2.2.5/dist/webblocks-ui.js
curl -O https://raw.githubusercontent.com/fklavyenet/webblocks-ui/v2.2.5/dist/webblocks-icons.svg
curl -O https://raw.githubusercontent.com/fklavyenet/webblocks-ui/v2.2.5/dist/webblocks-icons.css

Which option to choose? Use CDN for quick prototypes. Use ZIP/git clone for production projects where you want full control over versioning and offline availability.

Optional: Icons

For <i>-tag icon support, also include the icons CSS file. The SVG sprite is loaded separately (see below).

<!-- Optional: adds wb-icon-* classes for <i> tag usage -->
<link rel="stylesheet"
      href="https://cdn.jsdelivr.net/gh/fklavyenet/webblocks-ui@v2.3.5/dist/webblocks-icons.css">

Note: The icons CSS uses mask-image which requires a modern browser (Chrome 79+, Firefox 53+, Safari 15.4+). It is opt-in and kept in a separate file to avoid bloating the main bundle.

Your first page

The minimal HTML skeleton. The data-mode and data-accent attributes on <html> activate the theme engine.

<!DOCTYPE html>
<html lang="en" data-mode="light" data-accent="ocean">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My App</title>
  <link rel="stylesheet"
        href="https://cdn.jsdelivr.net/gh/fklavyenet/webblocks-ui@v2.3.5/dist/webblocks-ui.css">
</head>
<body>

  <button class="wb-btn wb-btn-primary">Hello, WebBlocks UI!</button>

  <script src="https://cdn.jsdelivr.net/gh/fklavyenet/webblocks-ui@v2.3.5/dist/webblocks-ui.js"></script>
</body>
</html>

Loading the SVG icon sprite

If you use inline SVG icons (<svg><use href="#wb-icon-..."></use></svg>), load the sprite with a small fetch snippet after your JS:

<script>
fetch('https://cdn.jsdelivr.net/gh/fklavyenet/webblocks-ui@v2.3.5/dist/webblocks-icons.svg')
  .then(function(r) { return r.text(); })
  .then(function(svg) {
    var parser = new DOMParser();
    var svgEl = parser.parseFromString(svg, 'image/svg+xml').documentElement;
    svgEl.style.cssText = 'position:absolute;width:0;height:0;overflow:hidden';
    document.body.insertBefore(svgEl, document.body.firstChild);
      if (window.WBTheme) window.WBTheme.sync();
  });
</script>

After loading, reference any icon like this:

<svg class="wb-icon" aria-hidden="true">
  <use href="#wb-icon-settings"></use>
</svg>

Theme setup

WebBlocks UI has a multi-axis theme engine. All axes are set on the <html> element via data-* attributes.

Attribute	Values	Default
data-mode	`light` · `dark` · `auto`	light
data-accent	`ocean` · `forest` · `sunset` · `royal` · `mint` · `amber` · `rose` · `slate-fire`	ocean
data-preset	`modern` · `minimal` · `rounded` · `bold` · `editorial`	—
data-radius	`sharp` · `soft`	—
data-density	`compact` · `comfortable`	—
data-shadow	`flat` · `soft`	—
data-font	`system` · `modern` · `editorial`	—
data-border	`none` · `subtle` · `medium` · `bold` · `dashed`	—

Combining axes

<!-- Dark mode, forest accent, compact density, sharp radius -->
<html data-mode="dark" data-accent="forest" data-density="compact" data-radius="sharp">

Using presets

Presets bundle multiple axes into a named style. Individual axis attributes override preset values.

<!-- Apply the "rounded" preset, then override just the accent color -->
<html data-preset="rounded" data-accent="rose">

Runtime theme switching

Use the WBTheme JS API to switch axes at runtime. Built-in data-wb-mode-cycle and data-wb-mode-set attributes make wire-up effortless.

<!-- Cycle through light → dark → auto on click -->
<button data-wb-mode-cycle>Toggle dark mode</button>

<!-- Set a specific mode -->
<button data-wb-mode-set="dark">Dark</button>
<button data-wb-mode-set="light">Light</button>

<!-- Set accent color -->
<button data-wb-accent-set="forest">Forest accent</button>

Or call the JS API directly:

WBTheme.setMode('dark');
WBTheme.setAccent('sunset');
WBTheme.setPreset('rounded');
WBTheme.setDensity('compact');

Note: data-mode is the correct attribute name — not data-theme. WBTheme persists the user's choice in localStorage automatically.

Writing components

Every WebBlocks UI component uses a wb- prefix. Components are plain HTML — no custom elements, no JS framework required.

Button variants

<button class="wb-btn wb-btn-primary">Primary</button>
<button class="wb-btn wb-btn-outline">Outline</button>
<button class="wb-btn wb-btn-ghost">Ghost</button>
<button class="wb-btn wb-btn-danger">Delete</button>

<!-- Sizes -->
<button class="wb-btn wb-btn-primary wb-btn-sm">Small</button>
<button class="wb-btn wb-btn-primary wb-btn-lg">Large</button>

Card

<div class="wb-card">
  <div class="wb-card-header">
    <h3 class="wb-card-title">Card title</h3>
  </div>
  <div class="wb-card-body">
    Card content goes here.
  </div>
  <div class="wb-card-footer">
    <button class="wb-btn wb-btn-primary wb-btn-sm">Save</button>
  </div>
</div>

Alert

<div class="wb-alert wb-alert-success">Record saved successfully.</div>
<div class="wb-alert wb-alert-danger">Something went wrong.</div>
<div class="wb-alert wb-alert-warning">Please review before publishing.</div>
<div class="wb-alert wb-alert-info">Your session expires in 10 minutes.</div>

Form field

<div class="wb-field">
  <label class="wb-label">Email</label>
  <input type="email" class="wb-input" placeholder="you@example.com">
  <p class="wb-field-hint">We'll never share your email.</p>
</div>

<!-- With error state -->
<div class="wb-field">
  <label class="wb-label">Name</label>
  <input type="text" class="wb-input is-invalid" value="x">
  <p class="wb-field-error">Name must be at least 2 characters.</p>
</div>

See the Components reference for all 40+ components with live examples and copy-ready code.

Dashboard shell

The dashboard shell provides the outer frame for admin panels: a collapsible sidebar, sticky topbar, and scrollable content area.

<div class="wb-dashboard-shell">

  <!-- Sidebar -->
  <aside class="wb-sidebar">
    <div class="wb-sidebar-brand">
      <a href="#">My App</a>
    </div>
    <nav class="wb-sidebar-nav">
      <a href="#" class="wb-sidebar-link is-active">Dashboard</a>
      <a href="#" class="wb-sidebar-link">Users</a>
      <a href="#" class="wb-sidebar-link">Settings</a>
    </nav>
  </aside>

  <!-- Main area -->
  <div class="wb-dashboard-body">
    <!-- Topbar -->
    <header class="wb-navbar">
      <button class="wb-btn wb-btn-ghost wb-btn-sm" data-wb-toggle="sidebar">
        ☰ Menu
      </button>
    </header>

    <!-- Content -->
    <main class="wb-dashboard-main">
      <div class="wb-container">
        <h1>Page title</h1>
        <p>Page content…</p>
      </div>
    </main>
  </div>

</div>

See the Layouts page for full shell breakdowns and all layout variants.

Laravel integration

WebBlocks UI works with any template language. Here's how to integrate it into a Laravel Blade project.

Recommended approach: CDN via layout

Add the CDN links to your base Blade layout:

<!-- resources/views/layouts/app.blade.php -->
<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}"
      data-mode="light"
      data-accent="ocean">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>@yield('title', config('app.name'))</title>

    <link rel="stylesheet"
          href="https://cdn.jsdelivr.net/gh/fklavyenet/webblocks-ui@v2.3.5/dist/webblocks-ui.css">

    @stack('styles')
</head>
<body>

  @yield('content')

  <script src="https://cdn.jsdelivr.net/gh/fklavyenet/webblocks-ui@v2.3.5/dist/webblocks-ui.js"></script>
  @stack('scripts')
</body>
</html>

Self-hosted via public folder

Copy dist/ files into your Laravel public/ directory and reference with the asset() helper:

<!-- public/vendor/webblocks-ui/webblocks-ui.css -->
<link rel="stylesheet" href="{{ asset('vendor/webblocks-ui/webblocks-ui.css') }}">
<script src="{{ asset('vendor/webblocks-ui/webblocks-ui.js') }}"></script>

CSRF meta tag for AJAX modules

If you use WBAjaxToggle or other AJAX features, add the CSRF meta tag and the module reads it automatically:

<!-- In <head> -->
<meta name="csrf-token" content="{{ csrf_token() }}">

Example: AJAX checkbox toggle

Toggle a model's status with a single checkbox and no custom JS:

<!-- In a Blade view -->
<input
  type="checkbox"
  class="wb-switch"
  data-wb-ajax-toggle
  data-wb-url="{{ route('users.toggle-active', $user) }}"
  data-wb-field="is_active"
  data-wb-success="Status updated"
  {{ $user->is_active ? 'checked' : '' }}
>

Important: WebBlocks UI uses plain HTML classes — there are no Blade components or Blade directives. HTML stays HTML, which means your templates work identically in Laravel, plain PHP, Django, Rails, or any other framework.

Vite users

You can mix WebBlocks UI (CDN or public folder) with Vite for your own app code. There is no need to import WebBlocks UI through Vite — it is intentionally kept outside the build pipeline.

<!-- Use CDN for WebBlocks UI, Vite for your own styles/scripts -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/fklavyenet/webblocks-ui@v2.3.5/dist/webblocks-ui.css">
@vite(['resources/css/app.css', 'resources/js/app.js'])

Next steps

You're set up. Here's where to go from here.

Explore the token system

Learn how design tokens work and how to override them to match your brand.
Foundation & Tokens →
Browse all components

Buttons, cards, modals, drawers, tables, forms, toasts and 30+ more.
Components →
Set up a dashboard layout

Dashboard shell, sidebar navigation, settings shell, and content shell.
Layouts →
Learn the JavaScript API

WBModal, WBDrawer, WBToast, WBAjaxToggle, WBTheme and 8 more modules.
JavaScript API →
Browse the icon set

152 Lucide icons with copy-ready SVG and <i>-tag snippets.
Icons →