Getting Started

Webbloqs provides reusable UI components as both web components and React components, backed by a token-based design system. The main packages are:

Package	Purpose
@webbloqs/elements	Lit web components (buttons, form fields, layout, and more)
@webbloqs/react	React wrappers for all elements
@webbloqs/themes	Theme implementations (snow-white, compatibility)
@webbloqs/design	SCSS design tokens
@webbloqs/proxies	React-to-custom-element bridge

Installation

pnpm add @webbloqs/elements @webbloqs/react @webbloqs/themes

Setup

Two things are required before using webbloqs components:

1. Import a theme

Import a theme in your application's main SCSS file. Snow-white is the recommended starter theme:

// app.scss
@use "@webbloqs/themes/lib/snow-white";

To apply your brand colors on top of snow-white, override the brand token — the color palette will automatically use your new token:

@use "@webbloqs/themes/lib/snow-white";

:root, :host {
    --wb-ds-color-brand--primary: #2563eb;
}

See Theming for the full theming guide.

2. Call initGlobals

Call initGlobals once at application startup to initialize the webbloqs runtime (media queries, icon system, translations):

import { initGlobals } from "@webbloqs/elements/lib/global/init-globals";

initGlobals({
    publicPath: "/webbloqs/css",
    spritemap: { icons: { /* your icon definitions */ } },
});

Some consumer projects wrap initGlobals in a project-specific function (e.g., initDesign() in ewz-design). Check your project's setup before calling initGlobals directly.

Your first component

import { Button } from "@webbloqs/react/lib/button";
import { Stack } from "@webbloqs/react/lib/stack";
import { TextField } from "@webbloqs/react/lib/text-field";

export const MyForm = () => (
    <Stack space="space--l">
        <TextField name="email" label="Email" type="email" required />
        <Button kind="primary" onClick={() => console.log("clicked")}>
            Submit
        </Button>
    </Stack>
);

Import convention

Always import from subpaths for tree-shaking:

// Correct — enables tree-shaking
import { Button } from "@webbloqs/react/lib/button";

// ⚠️ Avoid — imports the entire library
import { Button } from "@webbloqs/react";

Why subpath imports matter: Barrel imports bypass tree-shaking, pulling in all components. Some components have side effects that can break other functionality — particularly in SSR contexts. Use subpath imports until tree-shaking is fully addressed in webbloqs.

What's next

• Forms — Building forms with validation, multistep flows, and conditional fields
• Theming — Token architecture, applying themes, customizing components
• Custom Elements — Creating custom web components from React using @webbloqs/proxies
• Component Catalog — Interactive Storybook explorer for all components
• @webbloqs/proxies — CustomElement factory API and form association