> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beyondwords.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Player Provider

> Custom elements for providing and consuming the BeyondWords player instance.

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npx @beyondwords/cli components add player-provider --html
  ```

  ```bash pnpm theme={null}
  pnpm dlx @beyondwords/cli components add player-provider --html
  ```

  ```bash yarn theme={null}
  yarn dlx @beyondwords/cli components add player-provider --html
  ```

  ```bash bun theme={null}
  bunx --bun @beyondwords/cli components add player-provider --html
  ```
</CodeGroup>

## Usage

`<bw-player-provider>` creates a `BeyondWords.Player` and exposes it to
descendant elements. Extend `BwPlayerConsumer` to read it.

```html theme={null}
<bw-player-provider
  data-project-id="9504"
  data-content-id="ba00ef51-03ac-4a85-8b98-e45c957e8ef8"
  data-show-user-interface="false"
>
  <my-control></my-control>
</bw-player-provider>

<script type="module">
  import { BwPlayerConsumer } from "@/registry/html/PlayerProvider";

  class MyControl extends BwPlayerConsumer {
    connectedCallback() {
      super.connectedCallback();
      // `this._player` is the resolved BeyondWords player instance
      this.textContent = this._player?.playbackState ?? "idle";
    }
  }
  customElements.define("my-control", MyControl);
</script>
```

### API

* **`<bw-player-provider>`** creates the player from its `data-*` attributes (`data-project-id`, `data-content-id`, `data-source-id`, `data-playlist-id`, `data-player-style`, `data-show-user-interface`, plus inline `data-content`, `data-adverts`, `data-advert-index` and `data-analytics-consent`) and destroys it on disconnect.
* **`BwPlayerConsumer`** is the base class. It walks up the DOM to find its provider and exposes the player via the `_player` getter and the widget mode via `_mode`. Throws if no `<bw-player-provider>` ancestor exists.