@ascentra/apex-react

React 18 / 19 wrapper for the Apex configurator widget. Renders the <apex-widget> web component and exposes idiomatic React props, a forwarded ref, and React-style event handlers.

Install

npm install @ascentra/apex-react @ascentra/apex react react-dom

The core widget script (@ascentra/apex) is a peer dependency. You can either import it (so a bundler picks it up) or load it from the CDN as a <script> tag — either way, the custom element must be registered before <ApexWidget /> mounts.

Usage

As an npm dependency

import { ApexWidget } from "@ascentra/apex-react";
import "@ascentra/apex"; // registers <apex-widget>
import "@ascentra/apex/style.css";

export function ConfiguratorPage() {
  return (
    <ApexWidget
      apiUrl="https://api.apex.ascentra.io"
      apiKey="apex_widget_..."
      theme="light"
      height={600}
      width="100%"
      onQuoteSubmit={(event) => {
        console.log("Quote submitted:", event.detail);
      }}
    />
  );
}

Via CDN

If you load the bundle from the CDN, omit the import "@ascentra/apex" line:

<script
  src="https://cdn.ascentra.io/widget/latest/apex-widget.js"
  crossorigin="anonymous"
></script>

import { ApexWidget } from "@ascentra/apex-react";

export function ConfiguratorPage() {
  return <ApexWidget apiUrl="..." apiKey="..." />;
}

Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | apiUrl | string | yes | Apex API base URL | | apiKey | string | yes | Widget API key (apex_widget_...) | | theme | 'light' \| 'dark' \| 'system' | | Visual theme. Defaults to light | | height | string \| number | | Numbers are rendered as px | | width | string \| number | | | | initialRootItem | string | | Pre-select a root item by code | | initialItems | string[] | | Pre-select child items by code | | className | string | | Applied to the underlying custom element | | style | CSSProperties | | Inline styles on the custom element | | onReady | (event: CustomEvent) => void | | Fires once the catalog has loaded | | onItemSelect | (event: CustomEvent) => void | | Fires when a root product is selected (apex:rootitemselect) | | onAddonChange | (event: CustomEvent) => void | | Fires when add-on selection changes (apex:itemselectionchange) | | onQuoteSubmit | (event: CustomEvent) => void | | Fires when a quote is submitted | | onError | (event: CustomEvent) => void | | Fires on errors surfaced by the widget |

Refs

ApexWidget forwards a ref to the underlying HTMLElement:

const widgetRef = useRef<HTMLElement>(null);
// widgetRef.current is the <apex-widget> element
<ApexWidget ref={widgetRef} apiUrl="..." apiKey="..." />

Server-side rendering

The widget is browser-only — it relies on Shadow DOM and customElements.define. If you SSR (Next.js, Remix, etc.) load the wrapper dynamically:

import dynamic from "next/dynamic";
const ApexWidget = dynamic(
  () => import("@ascentra/apex-react").then((m) => m.ApexWidget),
  { ssr: false },
);

Versioning

@ascentra/apex-react ships in lockstep with @ascentra/apex. Both packages share the same version on every release.

License

MIT