HTML / Web Components - BEEQ Design System

BEEQ components are standard custom elements (<bq-button>, <bq-input>, and so on). Use this guide when you are not using @beeq/angular, @beeq/react, or @beeq/vue — for example static HTML, legacy apps, micro-frontends, or vanilla JS/TS with Vite.

No wrapper required

Work with native custom elements and DOM APIs — no framework-specific package.

CDN-friendly

Add a stylesheet and module script to any HTML page; no Node.js or bundler required.

Bundler-ready

Install @beeq/core with npm and use defineCustomElements() in TypeScript or JavaScript apps.

If you use Angular, React, Vue, or Next.js, prefer the matching framework guide for wrappers, forms, and stack-specific setup.

Get started

Check your project setup

Choose the path that matches how you build your app:

CDN — plain .html files, prototypes, or pages without a build step
Bundler — Vite, Webpack, or similar (Node.js 18+)

Add styles and register components

Follow the path you chose in Step 1 — CDN or Bundler. You only need one.

Already have @beeq/core installed from the Installation guide? Skip the CDN path and the npm install command below — go straight to defineCustomElements() in the Bundler section.

CDN

Link the BEEQ stylesheet and ESM bundle from a CDN. Components register automatically when the module loads.

index.html

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>BEEQ + HTML</title>
    <link
      rel="stylesheet"
      href="https://esm.sh/@beeq/core/dist/beeq/beeq.css"
    />
    <script
      type="module"
      src="https://esm.sh/@beeq/core/dist/beeq/beeq.esm.js"
    ></script>
  </head>
  <body>
    <bq-button appearance="primary">Hello BEEQ</bq-button>
  </body>
</html>

Bundler

Install @beeq/core with your package manager, then call defineCustomElements() at app startup:

npm install @beeq/core

Import global styles once, register custom elements at startup, and load your entry script from HTML:

@import "@beeq/core/dist/beeq/beeq.css";

You can use unpkg, jsDelivr, or esm.sh CDN providers — keep the CSS and JS URLs on the same provider and version.

The Vite example above applies to other bundlers too: copy SVGs into a public folder your app serves, then call setBasePath() with that URL (see Configure icons below).

Configure icons

Many BEEQ components rely on SVG icons. Your app must serve the SVG files and tell BEEQ where to find them.

The full BEEQ icon set has 9,000+ SVG files. Copying everything into your repo can slow local builds. Prefer a CDN for quick starts, or copy only the icons you use.

Setup via `data-beeq` attribute

This is the quickest way to set up BEEQ SVG icons for CDN pages and many bundler apps.Add the data-beeq attribute to the <script type="module"> tag pointing at the directory or a CDN URL that contains the SVG files. BEEQ reads this automatically.

index.html

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link
      rel="stylesheet"
      href="https://esm.sh/@beeq/core/dist/beeq/beeq.css"
    />
    <script
      type="module"
      src="https://esm.sh/@beeq/core/dist/beeq/beeq.esm.js"
      data-beeq="https://esm.sh/@beeq/core/dist/beeq/svg/"
    ></script>
  </head>
  <body>
    <bq-button appearance="primary">Save</bq-button>
  </body>
</html>

Setup via `setBasePath()`

With a bundler, you can include the SVG files in your build output and use setBasePath() to configure the base path for the SVG files.If you are using Vite, you can use the vite-plugin-static-copy plugin.Install the static copy plugin, copy SVGs into your build output, and call setBasePath() before rendering components that use icons:

npm install -D vite-plugin-static-copy

import { defineConfig } from "vite";
import { viteStaticCopy } from "vite-plugin-static-copy";

export default defineConfig({
  plugins: [
    viteStaticCopy({
      targets: [
        {
          src: "./node_modules/@beeq/core/dist/beeq/svg/*",
          dest: "icons/svg",
        },
      ],
    }),
  ],
});

When you use setBasePath(), you do not need a data-beeq attribute on the same page unless you want a fallback.

To copy only the icons your app uses instead of the full set, see Copy only the icons you need in the React guide (the same Vite plugin pattern works in vanilla projects).

Use components in markup

Add BEEQ tags to your HTML like any other element. Use attributes for static values and JavaScript properties when you need richer types (objects, arrays, booleans).

<bq-input name="email" type="email" placeholder="you@example.com" required>
  <bq-icon name="envelope" slot="prefix"></bq-icon>
</bq-input>
<bq-button id="submit" appearance="primary">Submit</bq-button>

const input = document.querySelector("bq-input");
input.value = "hello@beeq.design";

const button = document.querySelector("#submit");
button.addEventListener("bqClick", () => {
  console.log("Button clicked");
});

Listen to events

BEEQ components emit custom events prefixed with bq — for example bqClick, bqChange, bqBlur, bqSelect. Always prefer these over standard DOM events (click, change) when they exist: the bq variants carry structured detail payloads and reflect the component’s actual internal state, not just a raw DOM event. Every component’s API reference table lists which events it emits and what event.detail contains. Check the component page in the Components section before wiring a listener.

<bq-checkbox id="terms">I agree to the terms</bq-checkbox>
<bq-input id="email" type="email" placeholder="you@example.com"></bq-input>

<script type="module">
  // bqChange carries { checked: boolean } for checkbox
  document.querySelector("#terms").addEventListener("bqChange", (event) => {
    console.log("Checked:", event.detail.checked);
  });

  // bqChange carries { value: string } for input
  document.querySelector("#email").addEventListener("bqChange", (event) => {
    console.log("Value:", event.detail.value);
  });
</script>

Read structured payloads from event.detail. Avoid reading from event.target.value directly — it may not reflect the component’s latest internal state in all cases.

TypeScript support

Import event detail types and element interfaces from @beeq/core for full type safety:

import type { BqCheckboxCustomEvent } from "@beeq/core";

const checkbox = document.querySelector("bq-checkbox");
checkbox?.addEventListener(
  "bqChange",
  (event: BqCheckboxCustomEvent<{ checked: boolean }>) => {
    console.log(event.detail.checked);
  },
);

For DOM element typing, use the generated component interfaces from @beeq/core (for example HTMLBqButtonElement) where your editor supports them.

Properties, attributes, and slots

Approach	When to use
HTML attributes	Strings and simple static values (`appearance="primary"`)
Element properties	Booleans, numbers, objects, and dynamic values (`button.disabled = true`)
Slots	Project content into named areas (`slot="prefix"`, default slot for label text)

Boolean attributes follow standard HTML rules: presence means true unless the component documents otherwise. When in doubt, set the property in JavaScript:

document.querySelector("bq-button").disabled = true;

VS Code autocomplete

BEEQ ships HTML custom data for Visual Studio Code, which improves completion for bq-* tags and attributes. Create .vscode/settings.json in your project root:

{
  "html.customData": ["./node_modules/@beeq/core/dist/beeq.html-custom-data.json"]
}

Troubleshooting

Components render as plain tags (no styles or behavior)

Confirm the stylesheet is loaded (beeq.css) and the ESM bundle or defineCustomElements() ran before you interact with the components. Check the browser console for failed network requests.

Icons are not rendering

Check both of these:

SVG files are available at a public URL (CDN or copied into your app)
data-beeq points to that directory or setBasePath() uses the same public path your app serves
Icon name values match SVG file names (without .svg)

Event listeners never fire

Make sure you listen for the bq-prefixed event name (for example bqClick, not click) and attach the listener after the element exists in the DOM.

Property updates do not reflect in the UI

Set properties on the element instance (element.value = "...") rather than only changing attributes when the component expects a property binding.

Styles are missing in a bundler app

Import @beeq/core/dist/beeq/beeq.css once in a stylesheet your entry file loads. See Installation for the shared import pattern.

Next steps

Explore components

Browse component pages for props, events, slots, and examples.

Customize the theme

Review theming options if your product needs brand customization.

Open Storybook

Explore component states and interactions in the live component library.

Using a framework instead?

If your project uses a major frontend framework, the official wrappers improve forms, events, and developer experience:

Angular

Standalone components, forms, and value accessors.

React

PascalCase components and onBq... event props.

Next.js

SSR, layout setup, and client-only icon initialization.

Vue

Custom element compiler options and v-model support.

No wrapper required

CDN-friendly

Bundler-ready

​Get started

Check your project setup

Add styles and register components

​CDN

​Bundler

Configure icons

​Setup via data-beeq attribute

​Setup via setBasePath()

Use components in markup

​Listen to events

​TypeScript support

​Properties, attributes, and slots

​VS Code autocomplete

​Troubleshooting

​Next steps

Explore components

Customize the theme

Open Storybook

​Using a framework instead?

Angular

React

Next.js

Vue

Get started

CDN

Bundler

Setup via `data-beeq` attribute

Setup via `setBasePath()`

Listen to events

TypeScript support

Properties, attributes, and slots

VS Code autocomplete

Troubleshooting

Next steps

Using a framework instead?