# @brightcove/react-player-loader

> The official react component for the Brightcove Player

Latest version **1.5.1** (published 2025-10-17) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @brightcove/react-player-loader
pnpm add @brightcove/react-player-loader
yarn add @brightcove/react-player-loader
bun add @brightcove/react-player-loader
```

## Health

**Score 50/100 (C)** — status: stable.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 1.5.1 |
| Published | 2025-10-17 |
| First published | 2018-08-21 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 633.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 22 |
| Author | Brightcove, Inc. |
| Maintainers | brightcove-admin, bc-alive, lasanchezc, brightcove-user, myerramalla, wswanbeck, syseng, bcmauleon, paco_oblea_bc, barroyo, bmartinez, ackbabe, omartinez, mgonzalez_bc, muthukumar.bc, bvilvanathan, agarciabcov, palvarezbc, ericramos, carlosabajo, luis.garcia.brightcove, stuartmh, mshiwal, tnwanna, sbarrettbc, bc-srimron-soutter, bgs-devops, carredondo, dsalnikov, dawnpacko, xgarcia_npm, miklospocsaji_bc, imorones, melinda.darvasi, daniel_campos, adambertalanbc, gabor.kiacz.brightcove, rwinger, sravan.pbr, apenigalapati, ijunaidf, lmaultsby, bcc-bfranklin, sachin-brightcove, bc-jcuevas, pfbcove, luantafarelsilva, ld-bsp, sapa-bsp, alik-brightcove, kreynolds, bcdjones, awahabbc, alet-bsp, dc-bsp, jasd-bsp, dstabsp, fabioluccioletti, lucr-bsp, eld-bsp, etri-bsp, rbalajee, dvidaurri, gcastanheiro-bc |
| Keywords | audio, brightcove, media, player, react, react-component, video |

## Links

- npm: https://www.npmjs.com/package/@brightcove/react-player-loader
- Repository: https://github.com/brightcove/react-player-loader
- Homepage: https://github.com/brightcove/react-player-loader#readme
- Issues: https://github.com/brightcove/react-player-loader/issues
- npm.io page: https://npm.io/package/@brightcove/react-player-loader

## Dependencies (1)

- [@brightcove/player-loader](https://npm.io/package/@brightcove/player-loader.md) ^1.8.1

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 1.5.1 (latest) — 2025-10-17
- 1.5.0 — 2024-04-16
- 1.4.2 — 2022-07-19
- 1.4.1 — 2020-10-09
- 1.4.0 — 2020-01-31
- 1.3.0 — 2019-07-22
- 1.2.1 — 2019-07-08
- 1.2.0 — 2018-12-13
- 1.1.2 — 2018-10-05
- 1.1.1 — 2018-09-17
- 1.1.0 — 2018-09-12
- 1.0.4 — 2018-09-05
- 1.0.3 — 2018-09-05
- 1.0.2 — 2018-09-04
- 1.0.1 — 2018-08-30
- … 2 more at https://npm.io/package/@brightcove/react-player-loader/versions

## README

# @brightcove/react-player-loader

[![Build Status](https://travis-ci.org/brightcove/react-player-loader.svg?branch=master)](https://travis-ci.org/brightcove/react-player-loader)
[![Greenkeeper badge](https://badges.greenkeeper.io/brightcove/react-player-loader.svg)](https://greenkeeper.io/)

[![NPM](https://nodeico.herokuapp.com/@brightcove/react-player-loader.svg)](https://npmjs.com/package/@brightcove/react-player-loader)

A React component to load a Brightcove Player in the browser.

## Brightcove Player Support

This library has [the same support characteristics as the Brightcove Player Loader](https://github.com/brightcove/player-loader#brightcove-player-support).

## Table of Contents

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->


- [Installation](#installation)
- [Standard Usage with JSX](#standard-usage-with-jsx)
- [Props](#props)
  - [`attrs`](#attrs)
  - [`baseUrl`](#baseurl)
  - [`manualReloadFromPropChanges`](#manualreloadfrompropchanges)
  - [Other Props](#other-props)
- [Effects of Prop Changes](#effects-of-prop-changes)
- [View the Demo](#view-the-demo)
- [Alternate Usage](#alternate-usage)
  - [ES Module (without JSX)](#es-module-without-jsx)
  - [CommonJS](#commonjs)
  - [`<script>` Tag](#script-tag)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Installation

No matter how you use this component, the only place it is available is npm.

```sh
npm install --save @brightcove/react-player-loader
```

## Standard Usage with JSX

Most React applications are using JSX and the toolchain provided by `create-react-app`.

After installing, `import` the module and use the `ReactPlayerLoader` component like any other component in your React application:

> **NOTE:** `React`/`ReactDOM` are **NOT** required, they are only used here to show a complete working example!

```js
import React from 'react';
import ReactDOM from 'react-dom';
import ReactPlayerLoader from '@brightcove/react-player-loader';

let reactPlayerLoader;
const onSuccess = function(success) {

  // The player object or iframe element (depending on embed type) can be
  // accessed in two ways.
  // 
  // From the success object passed to the `onSuccess` callback:
  console.log(success.ref);

  // As a property of the component instance:
  console.log(reactPlayerLoader.player);
};

reactPlayerLoader = ReactDOM.render(
  <ReactPlayerLoader accountId='1234678' onSuccess={onSuccess}/>,
  document.getElementById('fixture')
);
```

See [Alternate Usage](#alternate-usage) below for less common ways to use this component.

## Props

### `attrs`

Type: `Object`

Provides attributes (props) to the component element.

For example, you may want to customize the `className` of the component (by default, `"brightcove-react-player-loader"`) by setting props on the component like so:

```jsx
<ReactPlayerLoader attrs={{className: 'my-custom-class'}} />
```

### `baseUrl`

Type: `string`

Used to override the base URL for the Brightcove Player being embedded.

Most users will never need this prop. By default, players are loaded from Brightcove's player CDN (`players.brightcove.net`).

### `manualReloadFromPropChanges`

Type: `boolean`

Used to specify if reloading the player after prop changes will be handled manually. This can be done by calling `refToReactPlayerLoader.loadPlayer()`.

See [Effects of Prop Changes](#effects-of-prop-changes) below for the effects of prop changes.

### Other Props

All props not specified above are passed to the [Brightcove Player Loader](https://github.com/brightcove/player-loader#parameters) with a few differences:

1. We cannot expose the Player Loader promise easily, so you must use the `onSuccess` and `onFailure` callbacks.
2. If you don't provide an `onFailure` callback, the failure will be handled by throwing an error.
3. We need to use `refNode` and `refNodeInsert` internally, so those props will be ignored.

## Effects of Prop Changes

When a prop passed to this component changes, it will have one of two effects:

1. Dispose/reload the player. This is the most common case.
1. Update the player's state (e.g. fetch a new video).

The following props will update the player's state _without_ a reload:

- `catalogSearch`
- `catalogSequence`
- `playlistId`
- `playlistVideoId`
- `videoId`

All other prop changes, excluding props that are `function`'s, will cause a complete dispose/reload.

## View the Demo

This repository includes a barebones demo/example page.

1. Clone the repository
2. Move into the repository
3. Run `npm install`
4. Run `npm start`
5. Navigate to `http://localhost:9999` in a browser

## Alternate Usage

### ES Module (without JSX)

After installation, `import` the module in your JavaScript and use the `ReactPlayerLoader` component like any other component in your React application:

> **NOTE:** `React`/`ReactDOM` are **NOT** required, they are only used here to show a complete working example!

```js
import React from 'react';
import ReactDOM from 'react-dom';
import ReactPlayerLoader  from '@brightcove/react-player-loader';

const reactPlayerLoader = ReactDOM.render(
  React.createElement(ReactPlayerLoader, {
    accountId: '1234678',
    onSuccess(success) {
      // two ways to get the underlying player/iframe at this point.
      console.log(success.ref)
      console.log(reactPlayerLoader.player);
    }
  }),
  document.getElementById('fixture')
);

```

### CommonJS

After installation, `require` the module in your JavaScript and use the `ReactPlayerLoader` component like any other component in your React application:

> **NOTE:** `React`/`ReactDOM` are **NOT** required, they are only used here to show a complete working example!

```js
var React = require('react');
var ReactDOM = require('react-dom');
var ReactPlayerLoader = require('@brightcove/react-player-loader');

var reactPlayerLoader = ReactDOM.render(
  React.createElement(ReactPlayerLoader, {
    accountId: '1234678',
    onSuccess: function(success) {
      // two ways to get the underlying player/iframe at this point.
      console.log(success.ref)
      console.log(reactPlayerLoader.player);
    }
  }),
  document.getElementById('fixture')
);

```

### `<script>` Tag

_This case is extremely unlikely to be used._

After installation or loading from a CDN, use a `script` tag to include the module in your HTML and use the global `window.BrightcoveReactPlayerLoader` to construct the component.

```html
<div id="fixture"></div>
<script src="//path/to/react.min.js"></script>
<script src="//path/to/react-dom.min.js"></script>
<script src="//path/to/brightcove-react-player-loader.min.js"></script>
<script>
  var React = window.React;
  var ReactDOM = window.ReactDOM;

  var reactPlayerLoader = ReactDOM.render(
    React.createElement(window.BrightcoveReactPlayerLoader, {
      accountId: '1234678',
      onSuccess: function(success) {
        // two ways to get the underlying player/iframe at this point.
        console.log(success.ref)
        console.log(reactPlayerLoader.player);
      }
    }),
    document.getElementById('fixture')
  );
</script>
```

[react]: https://www.npmjs.com/package/react
[react-dom]: https://www.npmjs.com/package/react-dom

---
_Source: https://npm.io/package/@brightcove/react-player-loader · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._