Erste Schritte

Installation

WebBlocks UI benötigt keinen Build-Schritt und hat null Abhängigkeiten. Wähle die Methode, die zu deinem Projekt passt.

CDN (für die meisten Projekte empfohlen)

Der schnellste Weg zum Einstieg. Dateien werden über jsDelivr aus GitHub-Releases bereitgestellt.

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

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

Herunterladen & Selbst hosten

Lade die kompilierten Dateien herunter und serve sie von deinem eigenen Server — keine Internetabhängigkeit, kein CDN.

Option A — Neueste Version herunterladen (ZIP)

Gehe zu github.com/fklavyenet/webblocks-ui/releases/latest
Unter Assets klicke auf Source code (zip)
ZIP entpacken, den dist/-Ordner in das Projekt kopieren
Dateien mit einem relativen Pfad referenzieren:

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

Option B — Mit git klonen

Das vollständige Repository klonen und die dist/-Dateien direkt verwenden. Jederzeit durch Pull auf die neueste Version aktualisieren.

# Repository klonen
git clone https://github.com/fklavyenet/webblocks-ui.git

# Oder eine bestimmte getaggte Version klonen
git clone --branch v2.2.5 --depth 1 https://github.com/fklavyenet/webblocks-ui.git

# Benötigte Dateien befinden sich in dist/
#   dist/webblocks-ui.css
#   dist/webblocks-ui.js
#   dist/webblocks-icons.svg   (für SVG-Sprite-Icons)
#   dist/webblocks-icons.css   (für <i>-Tag-Icons, optional)

Option C — Direkte Datei-Downloads

Einzelne Dateien direkt aus dem GitHub-Repository herunterladen ohne zu klonen:

# Kompilierte Dateien direkt herunterladen (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

Welche Option wählen? Verwende CDN für schnelle Prototypen. Verwende ZIP/git clone für Produktionsprojekte, bei denen du volle Kontrolle über Versionierung und Offline-Verfügbarkeit benötigst.

Optional: Icons

Für <i>-Tag-Icon-Unterstützung füge auch die Icons-CSS-Datei hinzu. Das SVG-Sprite wird separat geladen (siehe unten).

<!-- Optional: fügt wb-icon-*-Klassen für <i>-Tag-Verwendung hinzu -->
<link rel="stylesheet"
      href="https://cdn.jsdelivr.net/gh/fklavyenet/webblocks-ui@v2.3.5/dist/webblocks-icons.css">

Hinweis: Das Icons-CSS verwendet mask-image und erfordert einen modernen Browser (Chrome 79+, Firefox 53+, Safari 15.4+). Es ist optional und wird in einer separaten Datei gehalten, um das Hauptpaket nicht aufzublähen.

Deine erste Seite

Das minimale HTML-Grundgerüst. Die Attribute data-mode und data-accent auf <html> aktivieren die Theme-Engine.

<!DOCTYPE html>
<html lang="de" data-mode="light" data-accent="ocean">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Meine 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">Hallo, WebBlocks UI!</button>

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

Das SVG-Icon-Sprite laden

Wenn du Inline-SVG-Icons verwendest (<svg><use href="#wb-icon-..."></use></svg>), lade das Sprite mit einem kleinen fetch-Snippet nach deinem 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>

Nach dem Laden kannst du jedes Icon so referenzieren:

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

Theme einrichten

WebBlocks UI verfügt über eine mehrachsige Theme-Engine. Alle Achsen werden auf dem <html>-Element über data-*-Attribute gesetzt.

Attribut	Werte	Standard
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`	—

Achsen kombinieren

<!-- Dunkelmodus, Forest-Akzent, kompakte Dichte, scharfer Radius -->
<html data-mode="dark" data-accent="forest" data-density="compact" data-radius="sharp">

Presets verwenden

Presets bündeln mehrere Achsen in einem benannten Stil. Einzelne Achsen-Attribute überschreiben Preset-Werte.

<!-- "rounded"-Preset anwenden, dann nur die Akzentfarbe überschreiben -->
<html data-preset="rounded" data-accent="rose">

Theme zur Laufzeit wechseln

Verwende die WBTheme-JS-API, um Achsen zur Laufzeit zu wechseln. Die eingebauten Attribute data-wb-mode-cycle und data-wb-mode-set machen die Verdrahtung mühelos.

<!-- Durch light → dark → auto beim Klicken wechseln -->
<button data-wb-mode-cycle>Dunkelmodus umschalten</button>

<!-- Einen bestimmten Modus setzen -->
<button data-wb-mode-set="dark">Dunkel</button>
<button data-wb-mode-set="light">Hell</button>

<!-- Akzentfarbe setzen -->
<button data-wb-accent-set="forest">Forest-Akzent</button>

Oder die JS-API direkt aufrufen:

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

Hinweis: Der korrekte Attributname ist data-mode — nicht data-theme. WBTheme speichert die Benutzerwahl automatisch in localStorage.

Komponenten schreiben

Jede WebBlocks-UI-Komponente verwendet das wb--Präfix. Komponenten sind reines HTML — keine Custom Elements, kein JS-Framework erforderlich.

Button-Varianten

<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">Löschen</button>

<!-- Größen -->
<button class="wb-btn wb-btn-primary wb-btn-sm">Klein</button>
<button class="wb-btn wb-btn-primary wb-btn-lg">Groß</button>

Karte

<div class="wb-card">
  <div class="wb-card-header">
    <h3 class="wb-card-title">Kartentitel</h3>
  </div>
  <div class="wb-card-body">
    Karteninhalt kommt hier rein.
  </div>
  <div class="wb-card-footer">
    <button class="wb-btn wb-btn-primary wb-btn-sm">Speichern</button>
  </div>
</div>

Hinweis

<div class="wb-alert wb-alert-success">Datensatz erfolgreich gespeichert.</div>
<div class="wb-alert wb-alert-danger">Etwas ist schiefgelaufen.</div>
<div class="wb-alert wb-alert-warning">Bitte vor der Veröffentlichung prüfen.</div>
<div class="wb-alert wb-alert-info">Deine Sitzung läuft in 10 Minuten ab.</div>

Formularfeld

<div class="wb-field">
  <label class="wb-label">E-Mail</label>
  <input type="email" class="wb-input" placeholder="du@beispiel.de">
  <p class="wb-field-hint">Deine E-Mail wird niemals weitergegeben.</p>
</div>

<!-- Mit Fehlerzustand -->
<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">Der Name muss mindestens 2 Zeichen lang sein.</p>
</div>

Alle 40+ Komponenten mit Live-Beispielen und kopierfertigen Code-Snippets findest du in der Komponenten-Referenz.

Dashboard-Shell

Die Dashboard-Shell stellt den äußeren Rahmen für Admin-Panels bereit: eine einklappbare Sidebar, eine klebende Topbar und einen scrollbaren Inhaltsbereich.

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

  <!-- Sidebar -->
  <aside class="wb-sidebar">
    <div class="wb-sidebar-brand">
      <a href="#">Meine App</a>
    </div>
    <nav class="wb-sidebar-nav">
      <a href="#" class="wb-sidebar-link is-active">Dashboard</a>
      <a href="#" class="wb-sidebar-link">Benutzer</a>
      <a href="#" class="wb-sidebar-link">Einstellungen</a>
    </nav>
  </aside>

  <!-- Hauptbereich -->
  <div class="wb-dashboard-body">
    <!-- Topbar -->
    <header class="wb-navbar">
      <button class="wb-btn wb-btn-ghost wb-btn-sm" data-wb-toggle="sidebar">
        ☰ Menü
      </button>
    </header>

    <!-- Inhalt -->
    <main class="wb-dashboard-main">
      <div class="wb-container">
        <h1>Seitentitel</h1>
        <p>Seiteninhalt…</p>
      </div>
    </main>
  </div>

</div>

Vollständige Shell-Erklärungen und alle Layout-Varianten findest du auf der Layouts-Seite.

Laravel-Integration

WebBlocks UI funktioniert mit jeder Template-Sprache. So integrierst du es in ein Laravel-Blade-Projekt.

Empfohlener Ansatz: CDN über Layout

Füge die CDN-Links zu deinem Basis-Blade-Layout hinzu:

<!-- 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>

Selbst gehostet über public-Ordner

Kopiere die dist/-Dateien in das Laravel-public/-Verzeichnis und referenziere sie mit dem 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 für AJAX-Module

Wenn du WBAjaxToggle oder andere AJAX-Funktionen verwendest, füge das CSRF-Meta-Tag hinzu — das Modul liest es automatisch:

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

Beispiel: AJAX-Checkbox-Toggle

Den Status eines Modells mit einer einzigen Checkbox ohne eigenes JS umschalten:

<!-- In einer 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 aktualisiert"
  {{ $user->is_active ? 'checked' : '' }}
>

Wichtig: WebBlocks UI verwendet reine HTML-Klassen — es gibt keine Blade-Komponenten oder Blade-Direktiven. HTML bleibt HTML, was bedeutet, dass deine Templates in Laravel, Plain PHP, Django, Rails oder jedem anderen Framework identisch funktionieren.

Vite-Benutzer

Du kannst WebBlocks UI (CDN oder public-Ordner) mit Vite für deinen eigenen App-Code kombinieren. Es ist nicht notwendig, WebBlocks UI über Vite zu importieren — es wird absichtlich außerhalb der Build-Pipeline gehalten.

<!-- CDN für WebBlocks UI, Vite für eigene 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'])

Nächste Schritte

Du bist startklar. Hier geht es weiter.

Das Token-System erkunden

Lerne, wie Design-Tokens funktionieren und wie du sie überschreiben kannst, um deine Marke abzubilden.
Grundlagen & Tokens →
Alle Komponenten durchsuchen

Buttons, Karten, Modals, Drawer, Tabellen, Formulare, Toasts und 30+ weitere.
Komponenten →
Dashboard-Layout einrichten

Dashboard-Shell, Sidebar-Navigation, Einstellungs-Shell und Content-Shell.
Layouts →
JavaScript API lernen

WBModal, WBDrawer, WBToast, WBAjaxToggle, WBTheme und 8 weitere Module.
JavaScript API →
Das Icon-Set durchsuchen

152 Lucide-Icons mit kopierfertigen SVG- und <i>-Tag-Snippets.
Icons →