React - BEEQ Design System

BEEQ works best in React through @beeq/react, the official React wrapper around BEEQ web components. It gives you React-friendly components such as BqButton, BqInput, and BqCard, so you can work with props, events, and slots in a way that feels much closer to a native React library. If you are starting a new React project, we recommend using a modern setup such as Vite. If you are working in a server-rendered React framework like Next.js, use the dedicated framework guide instead, since client-side setup and asset handling may differ.

Real props

Pass component properties in a React-friendly way, including richer values such as arrays and objects.

Custom events

Listen to BEEQ events through onBq... handlers instead of wiring DOM listeners by hand.

Native-feeling DX

Work with PascalCase components such as BqButton, BqInput, and BqCard.

In the standard React integration flow, you do not need to manually import the BEEQ ESM bundle or call defineCustomElements() yourself.

Get started

You can add BEEQ to an existing React project in a few steps:

Check your project setup

Make sure your project already has:

react and react-dom version 18 or 19
Node.js 18+
a React application setup such as Vite

If you already have a React app running, you can usually add BEEQ without changing your overall project structure.

Install the packages

Install both the core package and the React wrapper:

npm install @beeq/core @beeq/react

What each package gives you:

@beeq/core includes the web components, styles, icons, and shared types
@beeq/react provides the React wrappers used in your application code

Add the global styles

Import the BEEQ stylesheet once in your application’s main CSS or SCSS file, then make sure that stylesheet is loaded from your app entry point.

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

If you use Sass or another CSS preprocessor, keep the full file extension in the import path.

Configure icons

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

Be aware that there are over 9k SVG files, which can slow down your development or bundling time. If your app only needs a smaller subset, consider copying only the icons you actually use rather than the full SVG folder.

Vite
CDN or existing icon source
Set base path via HTML
Copy only the icons you need

If you are using Vite, install the static copy plugin:

npm install -D vite-plugin-static-copy

Then copy the BEEQ SVG files from node_modules into your build output and set the base path during app startup.

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { viteStaticCopy } from "vite-plugin-static-copy";

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

Use the public URL that matches where your app serves the SVG files. In most React apps, an absolute path such as /icons/svg is safer than a relative path.

If your project already serves icons from another location, you can point BEEQ there instead:

import { setBasePath } from "@beeq/core";

setBasePath("https://cdn.jsdelivr.net/npm/heroicons@2.1.5/24/outline");

Make sure the icon names you use in BqIcon match the icon set you provide.

Another option is setting a <script> with data-beeq=<url_or_path_to_svg_directory> in your project HTML entry point. This is a convenient way to configure the base path without needing JavaScript imports.

<script data-beeq="https://cdn.jsdelivr.net/npm/heroicons@2.1.5/24/outline"></script>

If you don’t need the full set of 9k+ icons, you can copy only the ones you actually use into your project. This can speed up development and bundling time.You can do this manually by copying specific SVG files from node_modules/@beeq/core/dist/beeq/svg to a public folder in your app, then calling setBasePath() with the URL that matches where those files are served.For example, if you only need caret-down.svg, hand-waving.svg, thumbs-up.svg, user.svg, and x-circle.svg, copy those files to public/svg and call:

import { setBasePath } from "@beeq/core";

setBasePath("/svg");

There are components that rely on specific icons, so make sure to include any icons used by the components you use. For example, BqButton uses caret-down.svg for dropdown buttons, and BqInput uses x-circle.svg for the clear button. Keep the file names unchanged when copying, since BEEQ looks for specific icon names based on the file names.

If you want to automate this process, you can write a custom Vite plugin to copy only the icons you need during development and build. The key steps are:

Copy the SVG files from node_modules/@beeq/core/dist/beeq/svg to a public location in your app
Call setBasePath() with the URL that matches where those files are served

import { resolve, join } from 'node:path';
import { mkdir, copyFile, access } from 'node:fs/promises';
import type { Plugin } from 'vite';

interface CopyIconsOptions {
  iconNames: string[];
  outputPath?: string;
  sourceDir?: string;
}

// Custom plugin to copy specific SVG icons
function copyBeeqIcons(options: CopyIconsOptions): Plugin {
  const { iconNames, outputPath = 'icons', sourceDir = 'node_modules/@beeq/core/dist/beeq/svg' } = options;

  return {
    name: 'copy-beeq-icons',
    async buildStart() {
      const targetDir = resolve('public', outputPath);

      try {
        // Ensure target directory exists
        await mkdir(targetDir, { recursive: true });

        // Copy icons concurrently for better performance
        const results = await Promise.allSettled(
          iconNames.map(async (iconName) => {
            const fileName = iconName.endsWith('.svg') ? iconName : `${iconName}.svg`;
            const sourcePath = resolve(sourceDir, fileName);
            const targetPath = join(targetDir, fileName);

            try {
              await access(sourcePath);
              await copyFile(sourcePath, targetPath);

              console.log(`✓ Copied ${fileName} to ${outputPath}/`);
              return { success: true, fileName };
            } catch {
              console.warn(`⚠ Icon not found: ${fileName}`);
              return { success: false, fileName };
            }
          }),
        );

        const successful = results.filter((r) => r.status === 'fulfilled').length;;
        console.log(`📦 Successfully copied ${successful}/${iconNames.length} icons to ${outputPath}/`);
      } catch (error) {
        console.error('❌ Failed to copy icons:', error);
        throw error;
      }
    },
  };
}

export { copyBeeqIcons };

Render your first component

Once styles and icons are configured, you can import and use BEEQ components like any other React component:

import { BqButton, BqIcon } from "@beeq/react";

export default function App() {
  return (
    <BqButton onBqClick={() => console.log("Clicked")}>
      Save changes
      <BqIcon name="floppy-disk" slot="suffix" />
    </BqButton>
  );
}

That is enough to get started.

React usage patterns with BEEQ

Import components in PascalCase

Import BEEQ components from @beeq/react and use them as PascalCase React components:

import { BqButton, BqInput, BqCard } from "@beeq/react";

Use React prop names

Always use the JavaScript prop name in React instead of the HTML attribute name. Examples:

only-icon → onlyIcon
debounce-time → debounceTime
justify-content → justifyContent

import { BqButton, BqIcon, BqInput } from "@beeq/react";

export function Example() {
  return (
    <>
      <BqButton onlyIcon label="Notifications">
        <BqIcon name="bell-ringing" />
      </BqButton>

      <BqInput debounceTime={250} placeholder="Search" />
    </>
  );
}

Use `on...` handlers for BEEQ events

BEEQ custom events become React-style event props by adding the on prefix: • bqClick → onBqClick • bqInput → onBqInput • bqChange → onBqChange • bqFocus → onBqFocus

import { useState } from "react";
import { BqIcon, BqInput } from "@beeq/react";

export function NameField() {
  const [name, setName] = useState("");

  return (
    <BqInput
      placeholder="How should we call you?"
      debounceTime={250}
      onBqInput={(event) => setName(String(event.detail.value))}
    >
      <BqIcon name="user" slot="prefix" />
    </BqInput>
  );
}

Slots still use the slot prop

To place content into BEEQ slots in React, pass slot to the child element:

Calling component methods with a ref

Some BEEQ components expose methods you can call programmatically. BqDialog and BqDrawer, for example, have open() and close() methods. Use useRef with the underlying HTML element type to access them:

import { useRef } from "react";
import { BqButton, BqDialog } from "@beeq/react";

export function ConfirmDialog() {
  const dialogRef = useRef<HTMLBqDialogElement>(null);

  return (
    <>
      <BqButton onBqClick={() => dialogRef.current?.open()}>
        Open dialog
      </BqButton>

      <BqDialog ref={dialogRef}>
        <span slot="title">Are you sure?</span>
        <p>This action cannot be undone.</p>
        <div slot="buttons">
          <BqButton appearance="secondary" onBqClick={() => dialogRef.current?.close()}>
            Cancel
          </BqButton>
          <BqButton appearance="primary" onBqClick={() => dialogRef.current?.close()}>
            Confirm
          </BqButton>
        </div>
      </BqDialog>
    </>
  );
}

Complete example

This example puts a few common pieces together: styles, input handling, icons, and button events.

import { useState } from "react";
import { BqButton, BqCard, BqIcon, BqInput } from "@beeq/react";

export default function App() {
  const [count, setCount] = useState(0);
  const [name, setName] = useState("");

  return (
    <BqCard>
      <h1>Hello, {name || "stranger"}!</h1>

      <BqInput
        placeholder="How should we call you?"
        debounceTime={250}
        onBqInput={(event) => setName(String(event.detail.value))}
      >
        <BqIcon name="user" slot="prefix" />
      </BqInput>

      <BqButton onBqClick={() => setCount((current) => current + 1)}>
        Give a thumbs up
        <BqIcon name="thumbs-up" slot="suffix" />
      </BqButton>

      <p>Total of thumbs: {count}</p>
    </BqCard>
  );
}

Typescript notes

BEEQ also exports useful types from @beeq/core, including custom event types:

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

In many cases you will not need to annotate those types manually, especially when using inline handlers, because the React wrapper already provides enough type information for common cases. Use explicit event types when:

you want stronger typing in extracted handlers
you are working with more complex event payloads
you want clearer autocomplete in larger components

Read the updated value from event.detail.value — this is Stencil’s convention for custom event payloads. Avoid reading from event.target.value directly, as it may not reflect the component’s latest internal state in all cases.

Troubleshooting

Styles are missing

Make sure @beeq/core/dist/beeq/beeq.css is imported once in your app’s main stylesheet, and that the stylesheet is actually loaded by your entry file.

Icons are not rendering

Check both of these:

the SVG files are being served by your app
setBasePath() points to the same public URL where those files are available

Event handlers are not firing

Use wrapper components from @beeq/react and the onBq... props. If you render raw custom elements directly in React, event handling becomes less predictable.

Props are not working as expected

Make sure you are using the React prop names (camelCase) instead of the HTML attributeUse the React prop name, not the HTML attribute name. For example, use onlyIcon instead of only-icon, debounceTime instead of debounce-time, and justifyContent instead of justify-content.

I'm using a server-rendered React framework

Use the dedicated framework guide. Those setups often need client-only initialization or different handling for assets and hydration.

Next steps

Explore components

Start with a real component page to see props, events, slots, and framework 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.

Real props

Custom events

Native-feeling DX

​Get started

Check your project setup

Install the packages

Add the global styles

Configure icons

Render your first component

​React usage patterns with BEEQ

​Import components in PascalCase

​Use React prop names

​Use on... handlers for BEEQ events

​Slots still use the slot prop

​Calling component methods with a ref

​Complete example

​Typescript notes

​Troubleshooting

​Next steps

Explore components

Customize the theme

Open Storybook

Get started

React usage patterns with BEEQ

Import components in PascalCase

Use React prop names

Use `on...` handlers for BEEQ events

Slots still use the slot prop

Calling component methods with a ref

Complete example

Typescript notes

Troubleshooting

Next steps