Skip to main content
The elements ship as a shadcn registry. Add them with the CLI and the source is copied into your project. They also need the BeyondWords player script on the page.

​
Prerequisites

  • A project where you can run npx commands and serve ES modules. The CLI copies the element source into your project.
  • A BeyondWords project ID and a source ID (or content ID). The examples below use a public demo project.

​
Load the player script

The elements expect the BeyondWords player as a global BeyondWords. Add the player UMD script to your page so it loads before the provider connects:

​
Add a component

Add the Play Pause Button. No configuration is needed. The --html flag selects the HTML registry, and the CLI resolves dependencies automatically, so this also pulls in Player Provider and New Event.
The CLI copies the files to components/beyondwords/ by default (it asks first), or respects your aliases if the project has a components.json. The examples in these docs import from @/registry/html/. Adjust the paths to wherever the files landed, and serve them through a bundler or an import map so the browser can resolve them.

​
Build your first player

Each module calls customElements.define, so importing it registers the tag. Nest your controls inside a <bw-player-provider>, which mounts the player and shares it with the elements inside. data-show-user-interface="false" hides the player’s built-in UI so yours is the only one on the page.
Here’s that button running live: It looks plain because the elements are minimal by design; Theming shows how to make it yours. Add more controls the same way: import the module, nest the element inside the provider. To build your own controls, extend BwPlayerConsumer, which resolves the player instance from the nearest <bw-player-provider>. See Player Provider for the pattern, and New Event for emitting player events.

​
Using the shadcn CLI instead (optional)

The registry also works with the shadcn CLI directly. Add components by full URL:
Or register the registry namespace once in your components.json, then use short names:
components.json

​
Next steps

Theming

Style the elements to match your brand.

Player Provider

Provide and consume the player.

Examples

Start from a complete, pre-built player.

Troubleshooting

Fix common setup issues.