Primeros Pasos

Instalacion

WebBlocks UI no requiere paso de compilacion y tiene cero dependencias. Elige el metodo que mejor se adapte a tu proyecto.

CDN (recomendado para la mayoria de proyectos)

La forma mas rapida de empezar. Los archivos se sirven via jsDelivr desde las releases de GitHub.

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

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

Descargar y alojar en tu servidor

Descarga los archivos compilados y sirvelos desde tu propio servidor, sin dependencia de internet ni CDN.

Opcion A: Descargar la ultima version (ZIP)

Ve a github.com/fklavyenet/webblocks-ui/releases/latest
En Assets, haz clic en Source code (zip)
Extrae el ZIP, copia la carpeta dist/ a tu proyecto
Referencia los archivos con una ruta relativa:

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

Opcion B: Clonar con git

Clona el repositorio completo y usa los archivos dist/ directamente. Actualiza a la ultima version en cualquier momento con un pull.

# Clonar el repositorio
git clone https://github.com/fklavyenet/webblocks-ui.git

# O clonar una version especifica
git clone --branch v2.2.5 --depth 1 https://github.com/fklavyenet/webblocks-ui.git

# Los archivos necesarios estan en dist/
#   dist/webblocks-ui.css
#   dist/webblocks-ui.js
#   dist/webblocks-icons.svg   (para iconos SVG sprite)
#   dist/webblocks-icons.css   (para iconos con etiqueta <i>, opcional)

Opcion C: Descarga directa de archivos

Descarga archivos individuales directamente del repositorio sin clonar:

# Descargar archivos compilados directamente (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

Que opcion elegir? Usa CDN para prototipos rapidos. Usa ZIP/git clone para proyectos de produccion donde quieras control total sobre el versionado y la disponibilidad sin conexion.

Opcional: Iconos

Para soporte de iconos con etiqueta <i>, incluye tambien el archivo CSS de iconos. El SVG sprite se carga por separado (ver abajo).

<!-- Opcional: agrega clases wb-icon-* para uso con etiqueta <i> -->
<link rel="stylesheet"
      href="https://cdn.jsdelivr.net/gh/fklavyenet/webblocks-ui@v2.3.5/dist/webblocks-icons.css">

Nota: El CSS de iconos usa mask-image que requiere un navegador moderno (Chrome 79+, Firefox 53+, Safari 15.4+). Es opcional y se mantiene en un archivo separado para no inflar el bundle principal.

Tu primera pagina

El esqueleto HTML minimo. Los atributos data-mode y data-accent en <html> activan el motor de temas.

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

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

Cargar el sprite SVG de iconos

Si usas iconos SVG en linea (<svg><use href="#wb-icon-..."></use></svg>), carga el sprite con un pequeño fragmento fetch despues de tu 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>

Despues de cargar, referencia cualquier icono asi:

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

Configuracion del tema

WebBlocks UI tiene un motor de temas multi-eje. Todos los ejes se configuran en el elemento <html> mediante atributos data-*.

Atributo	Valores	Por defecto
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`	—

Combinar ejes

<!-- Modo oscuro, acento forest, densidad compacta, radio sharp -->
<html data-mode="dark" data-accent="forest" data-density="compact" data-radius="sharp">

Usar presets

Los presets agrupan multiples ejes en un estilo con nombre. Los atributos de eje individuales sobreescriben los valores del preset.

<!-- Aplicar el preset "rounded", luego sobreescribir solo el color de acento -->
<html data-preset="rounded" data-accent="rose">

Cambio de tema en tiempo de ejecucion

Usa la API JS WBTheme para cambiar ejes en tiempo de ejecucion. Los atributos integrados data-wb-mode-cycle y data-wb-mode-set facilitan la conexion.

<!-- Ciclar entre light, dark y auto al hacer clic -->
<button data-wb-mode-cycle>Alternar modo oscuro</button>

<!-- Establecer un modo especifico -->
<button data-wb-mode-set="dark">Oscuro</button>
<button data-wb-mode-set="light">Claro</button>

<!-- Establecer color de acento -->
<button data-wb-accent-set="forest">Acento forest</button>

O llamar a la API JS directamente:

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

Nota: El nombre de atributo correcto es data-mode — no data-theme. WBTheme guarda la eleccion del usuario en localStorage automaticamente.

Escribir componentes

Cada componente de WebBlocks UI usa el prefijo wb-. Los componentes son HTML puro: no se necesitan elementos personalizados ni framework JS.

Variantes de boton

<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">Eliminar</button>

<!-- Tamanos -->
<button class="wb-btn wb-btn-primary wb-btn-sm">Pequeno</button>
<button class="wb-btn wb-btn-primary wb-btn-lg">Grande</button>

Tarjeta

<div class="wb-card">
  <div class="wb-card-header">
    <h3 class="wb-card-title">Titulo de la tarjeta</h3>
  </div>
  <div class="wb-card-body">
    El contenido va aqui.
  </div>
  <div class="wb-card-footer">
    <button class="wb-btn wb-btn-primary wb-btn-sm">Guardar</button>
  </div>
</div>

Alerta

<div class="wb-alert wb-alert-success">Registro guardado correctamente.</div>
<div class="wb-alert wb-alert-danger">Algo salio mal.</div>
<div class="wb-alert wb-alert-warning">Por favor revisa antes de publicar.</div>
<div class="wb-alert wb-alert-info">Tu sesion expira en 10 minutos.</div>

Campo de formulario

<div class="wb-field">
  <label class="wb-label">Correo electronico</label>
  <input type="email" class="wb-input" placeholder="tu@ejemplo.com">
  <p class="wb-field-hint">Nunca compartiremos tu correo.</p>
</div>

<!-- Con estado de error -->
<div class="wb-field">
  <label class="wb-label">Nombre</label>
  <input type="text" class="wb-input is-invalid" value="x">
  <p class="wb-field-error">El nombre debe tener al menos 2 caracteres.</p>
</div>

Ve la referencia de Componentes para los 40+ componentes con ejemplos en vivo y codigo listo para copiar.

Dashboard shell

El dashboard shell proporciona el marco exterior para paneles de administracion: una barra lateral colapsable, una barra superior fija y un area de contenido desplazable.

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

  <!-- Barra lateral -->
  <aside class="wb-sidebar">
    <div class="wb-sidebar-brand">
      <a href="#">Mi App</a>
    </div>
    <nav class="wb-sidebar-nav">
      <a href="#" class="wb-sidebar-link is-active">Dashboard</a>
      <a href="#" class="wb-sidebar-link">Usuarios</a>
      <a href="#" class="wb-sidebar-link">Configuracion</a>
    </nav>
  </aside>

  <!-- Area principal -->
  <div class="wb-dashboard-body">
    <!-- Barra superior -->
    <header class="wb-navbar">
      <button class="wb-btn wb-btn-ghost wb-btn-sm" data-wb-toggle="sidebar">
        Menu
      </button>
    </header>

    <!-- Contenido -->
    <main class="wb-dashboard-main">
      <div class="wb-container">
        <h1>Titulo de pagina</h1>
        <p>Contenido de la pagina...</p>
      </div>
    </main>
  </div>

</div>

Ve la pagina de Layouts para desglose completo de shells y todas las variantes de layout.

Integracion con Laravel

WebBlocks UI funciona con cualquier lenguaje de plantillas. Aqui se muestra como integrarlo en un proyecto Laravel Blade.

Enfoque recomendado: CDN via layout

Agrega los enlaces CDN a tu layout base de Blade:

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

Autoalojado en la carpeta public

Copia los archivos dist/ en el directorio public/ de Laravel y referencialos con el helper asset():

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

Meta tag CSRF para modulos AJAX

Si usas WBAjaxToggle u otras funciones AJAX, agrega el meta tag CSRF y el modulo lo leera automaticamente:

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

Ejemplo: toggle de checkbox AJAX

Cambia el estado de un modelo con un solo checkbox sin JS personalizado:

<!-- En una vista Blade -->
<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="Estado actualizado"
  {{ $user->is_active ? 'checked' : '' }}
>

Importante: WebBlocks UI usa clases HTML puras: no hay componentes Blade ni directivas Blade. HTML se mantiene como HTML, lo que significa que tus plantillas funcionan identicamente en Laravel, PHP puro, Django, Rails o cualquier otro framework.

Usuarios de Vite

Puedes combinar WebBlocks UI (CDN o carpeta public) con Vite para tu propio codigo de app. No es necesario importar WebBlocks UI a traves de Vite: se mantiene intencionalmente fuera del pipeline de compilacion.

<!-- CDN para WebBlocks UI, Vite para tus propios estilos/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'])

Proximos pasos

Ya estas listo. Aqui tienes a donde ir a continuacion.

Explorar el sistema de tokens

Aprende como funcionan los design tokens y como sobreescribirlos para adaptarlos a tu marca.
Fundamentos y Tokens
Ver todos los componentes

Botones, tarjetas, modales, drawers, tablas, formularios, toasts y 30+ mas.
Componentes
Configurar un layout de dashboard

Dashboard shell, navegacion de barra lateral, settings shell y content shell.
Layouts
Aprender la JavaScript API

WBModal, WBDrawer, WBToast, WBAjaxToggle, WBTheme y 8 modulos mas.
JavaScript API
Explorar el conjunto de iconos

152 iconos Lucide con snippets SVG y de etiqueta <i> listos para copiar.
Iconos