Skip to content
OpenWaggle
Applies to @openwaggle/[email protected]

@openwaggle/extension-react

React components for OpenWaggle extension surfaces that use the SDK 0.2 theme contract.

@openwaggle/extension-react provides small React components for extension surfaces that should match OpenWaggle without importing application renderer code, including host-themed source rendering.

Use it when an extension contribution is implemented in React and should match the OpenWaggle extension theme contract. It is optional. Non-React extensions can use @openwaggle/extension-sdk UI helpers directly.

react and react-dom are peer dependencies. The supported peer line is React 19.

Import the default host-aligned stylesheet once in the extension bundle:

import '@openwaggle/extension-react/styles.css'

Mount a React surface

import '@openwaggle/extension-react/styles.css'
import type { OpenWaggleFederatedModule } from '@openwaggle/extension-sdk'
import { Badge, Button, Field, Input, Panel, Stack } from '@openwaggle/extension-react'
import { createRoot } from 'react-dom/client'

function SettingsSurface() {
  return (
    <Panel>
      <Stack gap="0.75rem">
        <Badge tone="info">Project</Badge>
        <Field htmlFor="default-label" label="Default label">
          <Input id="default-label" defaultValue="Architect" />
        </Field>
        <Button type="button" variant="primary">Save</Button>
      </Stack>
    </Panel>
  )
}

export const mount: OpenWaggleFederatedModule['mount'] = (context) => {
  const root = createRoot(context.root)
  root.render(<SettingsSurface />)
  return () => root.unmount()
}

The OpenWaggle host adds .ow-extension-root to context.root and projects the SDK 0.2 appearance variables onto it. Standalone harnesses must add the same class and provide the SDK theme variables before rendering the components.

Use the broker SDK from context.sdk or @openwaggle/extension-sdk for persistence and OpenWaggle capability calls. The React package only supplies UI components.

Migrating from 0.1

Version 0.2 replaces the bespoke 0.1 spacing, radius, elevation, and fallback values with the Tailwind-standard extension theme contract from @openwaggle/extension-sdk 0.2.

  • Root. Mount all components beneath .ow-extension-root. The 0.2 stylesheet styles components only inside an element with that class.
  • Spacing. Replace --ow-space-* overrides with multiples of --ow-spacing.
  • Radius. Panels now use --ow-radius-3xl instead of --ow-radius-panel. Badges use --ow-radius-md, and buttons, inputs and alerts use --ow-radius-lg. An override of --ow-radius-panel or --ow-radius-sm no longer changes any component.
  • Shadow and type. Replace --ow-elevation-card with --ow-shadow-sm. Text sizes come from the projected text-size and line-height pairs.
  • Text colours. Danger and info text now read --ow-color-danger-text and --ow-color-info-text. An override of --ow-color-danger or --ow-color-info no longer changes text colour.
  • Fallbacks. Do not rely on stylesheet fallback colours. The host or standalone harness provides the complete theme projection.
  • SDK. The package now depends on @openwaggle/extension-sdk 0.2 (^0.2.0). Upgrade both together.

New in 0.2: the SyntaxBlock and SourceView components for host-highlighted source.

Components

The package exports Alert, Badge, Button, Checkbox, Field, Input, Panel, Select, Stack, Textarea, SyntaxBlock, and SourceView. Pass context.sdk.surface.syntax to the syntax components. The host supplies the active theme and worker-backed tokenization. See the visual component catalogue and complete API reference.

These components use extension SDK class names and data attributes. They are not OpenWaggle app renderer components and they do not import the app’s Tailwind or renderer CSS.

When not to use it

Do not use @openwaggle/extension-react if your extension uses plain DOM, Vue, Preact, Svelte, or another renderer. The federated-module contract is framework-neutral, so those extensions can use @openwaggle/extension-sdk types, theme helpers, and UI stylesheet helpers directly.

Do not import OpenWaggle renderer components to fill gaps. If a component is missing, build a scoped extension-owned component on top of the extension UI style contract.

Compatibility

RequirementSupported line
Node.js22.19 and newer
React19.x
React DOM19.x
Extension SDK0.2.x
Module formatESM and CommonJS
OpenWaggle package docs0.2

Reference and support

Troubleshooting

Components render without OpenWaggle styling. Import @openwaggle/extension-react/styles.css once in the extension bundle, and render the components beneath .ow-extension-root.

React is installed twice. Keep compatible React and React DOM versions in your extension project and deduplicate them in its build. The host does not supply React through the extension mount context. Your bundler must produce a browser-loadable artifact.

A non-React extension needs the same visual language. Use the framework-neutral classes and stylesheet helpers from @openwaggle/extension-sdk instead.