@beeq/react

React Wrapper for BEEQ

A lightweight utility that wraps BEEQ custom elements ("web components") so they can be used like native React components.

Why is this necessary?

React and custom elements don't play nicely together. The problem is best described by Custom Elements Everywhere:

Handling data

React passes all data to Custom Elements in the form of HTML attributes. For primitive data this is fine, but the system breaks down when passing rich data, like objects or arrays. In these instances you end up with stringified values like some-attr="[object Object]" which can't actually be used.

Handling events

Because React implements its own synthetic event system, it cannot listen for DOM events coming from Custom Elements without the use of a workaround. Developers will need to reference their Custom Elements using a ref and manually attach event listeners with addEventListener. This makes working with Custom Elements cumbersome.

This utility solves these problems by exposing a native React component that maps properties and events to the underlying custom element. ✨

Package installation

[!TIP] Please always refer to the official BEEQ documentation for more information about the installation.

• install the package

npm install @beeq/{core,react}

[!NOTE] Make sure that you have installed the @beeq/core package.

Add BEEQ styles and assets

Import BEEQ styles into your application's main style file:

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

[!TIP] BEEQ uses SVG icons and these assets are shipped in a separate folder. You can use the setBasePath method to set the path to the icons. Make sure that your project bundle the icons in a way that they are accessible from the browser.

You can move the icons from the node_modules folder to your assets folder and set the path like this:

// vite.config.js
import { defineConfig } from 'vite';
import { viteStaticCopy } from 'vite-plugin-static-copy';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [
    react(),
    viteStaticCopy({
      targets: [
        {
          src: './node_modules/@beeq/core/dist/beeq/svg/*',
          dest: 'icons/svg',
        },
        // add more targets if needed
      ],
    }),
  ],
  // other configurations
});

// main.ts
import { setBasePath } from "@beeq/core/dist/components";

setBasePath('icons/svg');

Please, notice the path 👆

But you can also use a different icons library or a CDN:

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

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

[!CAUTION] When using a different icons library, make sure you use the correct icon names provided by the library or the CDN.

Usage

import React from 'react';
import { BqButton } from '@beeq/react';

function App() {
  const handleButtonClick = (ev: CustomEvent) => {
    console.log(ev.detail);
  };

  return (
    <BqButton appearance="primary" onBqClick={handleButtonClick}>
      Click Me
    </BqButton>
  );
}

export default App;

Changelog

1.9.0 (2025-04-29)

Features ⚡️

• Select: add bqInput event for real-time input value changes when filtering (#1476)
• Select: add reset method to restore to a previous value (#1477)

Bug Fixes 🐞

• Dialog: change positioning from absolute to fixed (#1464)
• Select: change value clearing logic to use empty string instead undefined (#1475)

Documentation 📚

• README: enhance structure and content for better navigation and clarity (ba586bf)
• README: enhance development section with PNPM commands and NX tips (e256b34)

Chore ⚙️

• ESLint: enable cache (ff4a4b1)
• Workspace: move from NPM to PNPM (#1442)
• deps: update storybook to v8.6.3 (#1443)
• deps: update nx to v20.4.6 (#1444)
• deps: update stencil (b839181)
• deps: update pnpm to v10.6.2 (#1449)
• deps: update storybook to v8.6.4 (#1446)
• deps: update node.js to v22.14.0 (#1447)
• deps: update nx to v20.5.0 (#1448)
• deps: update @stencil/sass to v3.1.9 and silence deprecation warnings (#1450)
• deps: update @stencil/core, @stencil/sass and @stencil/vue-output-target dependencies (#1452)
• deps: update dependency @stencil/sass to v3.2.1 (#1453)
• deps: update storybook to v8.6.12 (#1456)
• deps: update nx to v20.8.0 (#1457)
• deps: update react to v19.1.0 (#1454)
• deps: update types react to v19.1.2 (#1455)
• deps: update angular to v18.2.18 (#1459)
• deps: update eslint (#1458)
• deps: update commitlint to v19.8.0 (#1460)
• deps: update dependency stylelint to v16.18.0 (#1462)
• deps: update pnpm to v10.9.0 (#1463)
• deps: update node.js to v22.15.0 (#1466)
• deps: update lit to v3.3.0 (#1465)
• deps: update dependency puppeteer to v24.7.1 (#1467)
• deps: update dependency ts-jest to v29.3.2 (#1468)
• deps: update dependency stylelint to v16.19.0 (#1469)
• deps: update dependency @chromatic-com/storybook to v3.2.6 (#1471)
• deps: update angular to v18.2.19 (#1470)
• deps: update nx to v20.8.1 (#1473)
• deps: update dependency chromatic to v11.28.2 (#1472)
• deps: update @stencil/{core, react-output-target} to v4.30.0 and v1.0.2 (#1474)
• deps: sync @beeq/core version in the wrapper packages (36870b9)
• volta: update Node.js hooks to use official distribution URLs (95e2764)

Style 🎨

• Select: remove console log leftover from handleInput method (5184673)

❤️ Thank You

• Dabiel González Ramos @dgonzalezr