React SDK

The @dial-beacon/react package provides a React component and hook for integrating Beacon into React and Next.js applications.

Installation


npm install @dial-beacon/react
# or
pnpm add @dial-beacon/react
# or
yarn add @dial-beacon/react

DialBeacon Component

The main component loads the Beacon CDN script and initializes the widget.


import { DialBeacon } from '@dial-beacon/react';
 
function App() {
  return (
    <>
      <YourApp />
      <DialBeacon projectId="your-project-id" />
    </>
  );
}

The component renders null — Beacon injects its own DOM elements. Place it anywhere in your component tree.

Props

Prop	Type	Required	Default	Description
`projectId`	string	Yes	—	Your Beacon project ID
`env`	`"prod"` \| `"staging"`	No	`"prod"`	Environment
`publicKey`	string	No	—	Publishable key for domain validation
`apiBase`	string	No	—	Custom API base URL
`scriptSrc`	string	No	CDN URL	Custom script source
`overrides`	object	No	—	Config overrides merged on top of remote config
`configMode`	`"remote"` \| `"local"`	No	`"remote"`	Config fetch mode
`onEvent`	function	No	—	Callback for Beacon events

Config Overrides

Override specific config values while keeping the rest from the remote config:


<DialBeacon
  projectId="your-project-id"
  overrides={{
    branding: { accentColor: '#ff6600' },
    placement: { position: 'bottom-left' },
  }}
/>

Local Config Mode

For development or fully client-side config:


<DialBeacon
  projectId="dev-project"
  configMode="local"
  overrides={{
    branding: { name: 'Dev Support' },
    lanes: {
      support: { enabled: true, label: 'Help' },
      sales: { enabled: false, label: 'Sales' },
      community: { enabled: false, label: 'Community' },
    },
    quickActions: [
      { id: 'help', label: 'Get Help', lane: 'support', type: 'open_chat' },
    ],
  }}
/>

Event Handling

Listen to Beacon events via the onEvent callback:


<DialBeacon
  projectId="your-project-id"
  onEvent={(event, payload) => {
    console.log('Beacon event:', event, payload);
 
    if (event === 'beacon_opened') {
      analytics.track('support_widget_opened');
    }
  }}
/>

Events are dispatched as CustomEvent on the dial-beacon-event event name.

useDialBeacon Hook

For programmatic control over the Beacon widget:


import { useDialBeacon } from '@dial-beacon/react';
 
function SupportButton() {
  const { open, close, toggle, trackConversion, identify } = useDialBeacon();
 
  return (
    <button onClick={open}>
      Need Help?
    </button>
  );
}

Methods

Method	Description
`open()`	Open the Beacon panel
`close()`	Close the Beacon panel
`toggle()`	Toggle the panel open/closed
`trackConversion(name)`	Send a conversion event
`identify(data)`	Associate visitor data

DialBeaconMock

A mock component for development and testing that doesn’t load the CDN script:


import { DialBeaconMock } from '@dial-beacon/react';
 
function DevApp() {
  return (
    <>
      <YourApp />
      <DialBeaconMock
        projectId="test-project"
        config={{
          branding: { name: 'Test Support' },
        }}
      />
    </>
  );
}

Next.js Integration

For Next.js App Router, add Beacon to your root layout:


// app/layout.tsx
import { DialBeacon } from '@dial-beacon/react';
 
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <DialBeacon projectId="your-project-id" />
      </body>
    </html>
  );
}

Since DialBeacon uses useEffect and useRef, it’s a client component internally. You don’t need to add 'use client' to your layout — the component handles that.

Cleanup

The component automatically cleans up when unmounted:

Removes the Beacon root element
Removes injected styles
Cleans up global window.DialBeacon reference