# react-spotify-web-playback-sdk

> React Wrapper of Spotify Web Playback SDK

Latest version **3.0.3** (published 2025-09-27) · MIT license · 0 weekly downloads

## Install

```sh
npm install react-spotify-web-playback-sdk
pnpm add react-spotify-web-playback-sdk
yarn add react-spotify-web-playback-sdk
bun add react-spotify-web-playback-sdk
```

## Health

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

Positive: has types; esm support; no vulnerabilities; has provenance; high quality score.

Warnings: low downloads.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 3.0.3 |
| Published | 2025-09-27 |
| First published | 2021-04-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 60.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 72 |
| Author | https://github.com/y-hiraoka |
| Maintainers | y-hiraoka |
| Keywords | react, spotify, web-playback-sdk |

## Links

- npm: https://www.npmjs.com/package/react-spotify-web-playback-sdk
- Repository: https://github.com/y-hiraoka/react-spotify-web-playback-sdk
- Homepage: https://github.com/y-hiraoka/react-spotify-web-playback-sdk#readme
- Issues: https://github.com/y-hiraoka/react-spotify-web-playback-sdk/issues
- npm.io page: https://npm.io/package/react-spotify-web-playback-sdk

## Dependencies (1)

- [@types/spotify-web-playback-sdk](https://npm.io/package/@types/spotify-web-playback-sdk.md) ^0.1.12

## 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

- 3.0.3 (latest) — 2025-09-27
- 3.0.2 — 2023-06-06
- 3.0.1 — 2022-02-16
- 3.0.0 — 2022-02-16
- 2.0.0 — 2021-05-29
- 1.0.4 — 2021-05-10
- 1.0.3 — 2021-05-10
- 1.0.2 — 2021-05-04
- 1.0.1 — 2021-04-28
- 1.0.0 — 2021-04-28
- 0.0.2 — 2021-04-21
- 0.0.1 — 2021-04-21

## README

<p align="center"><img src="react-spotify-web-playback-sdk-logo.png"></p>

# react-spotify-web-playback-sdk

[日本語](README-ja.md)

This is a React wrapper for [Spotify Web Playback SDK](https://developer.spotify.com/documentation/web-playback-sdk/).

By using this library, you can use declaratively handle the Spotify player.

## Why?

Spotify Web Playback SDK will be not published in npm registory and downloaded from CDN.
So when you use it, you must add a script tag. But it's not desirable.
If you use this wrapper library, you don't have to add script tag to head of html.

The plain SDK does not have a declarative API. So, when you use it in your React app, you will probably find it hard to do. Using this library, you can handle the data provided by the SDK with custom hooks that you are used to.

## Getting Started

### Install

```
npm install react-spotify-web-playback-sdk
```

### `WebPlaybackSDK`

Assume that you have the latest oauth token. Required scopes that the token have are `"streaming"`, `"user-read-email"` and `"user-read-private"`. You can also get an access token [here](https://developer.spotify.com/documentation/web-playback-sdk/quick-start).

`WebPlaybackSDK` component is a root of this library. So you must wrap any custom-hooks in this library with it.

```tsx
import { WebPlaybackSDK } from "react-spotify-web-playback-sdk";

const AUTH_TOKEN = "your token here!";

const MySpotifyPlayer: React.VFC = () => {
  const getOAuthToken = useCallback(callback => callback(AUTH_TOKEN), []);

  return (
    <WebPlaybackSDK
      initialDeviceName="My awesome Spotify app"
      getOAuthToken={getOAuthToken}
      initialVolume={0.5}>
      {/* `TogglePlay` and `SongTitle` will be defined later. */}
      <TogglePlay />
      <SongTitle />
    </WebPlaybackSDK>
  );
};
```

`props.initialDeviceName` is a value that will be displayed in the official Spotify app as the device name.

`props.getOAuthToken` is a function that takes a `callback` function as an argument to receive the access token.

`props.initialVolume` is a value between 0 and 1. If not specified, it will be set to the default value of 1.

The `props.initialVolume` can be a value between 0 and 1. If not specified, `1` will be set as the default value.

### `useSpotifyPlayer`

Gets the playback status. For example, there are properties such as whether it is paused or not, and the playback position.

```tsx
import { usePlaybackState } from "react-spotify-web-playback-sdk";

const SongTitle: React.VFC = () => {
  const playbackState = usePlaybackState();

  if (playbackState === null) return null;

  return <p>Current song: {playbackState.track_window.current_track.name}</p>;
};
```

If the connection with Spotify has not been established, it will be null, so perform a null check.

### Try to play

When you render `MySpotifyPlayer` in your React app, you will see `My awesome Spotify app` in Spotify Connect in your Spotify mobile app. Select it there and click the `toggle play` button to start playing.

## API

### `WebPlaybackSDK`

This is a React component that wraps the SDK. This is not available in the React-Naitive environment.

The custom hooks included in the library will not work unless they are inside this component.

#### `props`

| prop name              | type                                        | default value | description                                                                                   |
| :--------------------- | :------------------------------------------ | ------------- | --------------------------------------------------------------------------------------------- |
| `initialDeviceName`    | string                                      | (required)    | an initial value of Spotify Connect player name.                                              |
| `getOAuthToken`        | (callback: (token: string) => void) => void | (required)    | a function called when `player.connect()` is called, or when the user's access token expires. |
| `initialVolume`        | number                                      | 1             | a initial value of volume. specified as a decimal number between 0 and 1.                     |
| `connectOnInitialized` | boolean                                     | true          | Whether to make a connection at the same time as initialization.                              |

#### usage

```tsx
const MyPlayer = () => {
  const getOAuthToken = useCallback(callback => {
    const token = fetchNewSpotifyToken();
    callback(token);
  }, []);

  return (
    <WebPlaybackSDK
      initialDeviceName="My Spotify App"
      getOAuthToken={getOAuthToken}
      initialVolume={0.5}
      connectOnInitialized={true}>
      <SomeComponentsUsingCustomHook />
    </WebPlaybackSDK>
  );
};
```

### `useWebPlaybackSDKReady`

A custom hook that returns a boolean value whether the SDK has been downloaded and is ready or not.

#### type definition

```ts
function useWebPlaybackSDKReady(): boolean;
```

#### usage

```tsx
const MyPlayer = () => {
  const webPlaybackSDKReady = useWebPlaybackSDKReady();

  if (!webPlaybackSDKReady) return <div>Loading...</div>;

  return <div>Spotify App is ready!</div>;
};
```

### `useSpotifyPlayer`

A custom hook that returns an object with functions to manipulate the player, such as `resume()` or `seek(pos)`.

#### type definition

```ts
function useSpotifyPlayer(): Spotify.Player | null;
```

#### usage

```tsx
const PauseResumeButton = () => {
  const player = useSpotifyPlayer();

  if (player === null) return null;

  return (
    <div>
      <button onClick={() => player.pause()}>pause</button>
      <button onClick={() => player.resume()}>resume</button>
    </div>
  );
};
```

### `usePlaybackState`

A custom hook to get an object representing the player's playback state. See [the Spotify for Developers reference](https://developer.spotify.com/documentation/web-playback-sdk/reference/#objects) for more information on the properties that the object has.

If `interval` is `true`, state updates will occur during playback at the interval specified by `durationMS`. Even if it is `false`, state updates by `SpotifyPlayer.pause` and `SpotifyPlayer.resume` will occur.

#### type definition

```ts
function usePlaybackState(
  interval?: boolean = false,
  durationMS?: number = 1000,
): Spotify.PlaybackState | null;
```

#### usage

```tsx
const SongTitle: React.VFC = () => {
  const playbackState = usePlaybackState();

  if (playbackState === null) return null;

  return <p>Current song: {playbackState.track_window.current_track.name}</p>;
};
```

### `usePlayerDevice`

A custom hook that retrieves an object that represents the state of the player device. According to [the Spotify for Developers reference](https://developer.spotify.com/documentation/web-playback-sdk/reference/#event-not-ready), it will be `"not_ready"` when there is no internet connection.

The `device_id` can be used as a parameter to, for example, the Spotify Web API's playback API ([for reference](https://developer.spotify.com/documentation/web-api/reference/#endpoint-start-a-users-playback)).

#### type definition

```ts
type PlayerDevice = {
  device_id: string;
  status: "ready" | "not_ready";
};

function usePlayerDevice(): PlayerDevice | null;
```

#### ussage

```tsx
const SPOTIFY_URI = "spotify:track:7xGfFoTpQ2E7fRF5lN10tr";

const PlayCarlyRaeJepsen = () => {
  const device = usePlayerDevice();

  const playCarlyRaeJepsen = () => {
    if (device === null) return;

    fetch(
      `https://api.spotify.com/v1/me/player/play?device_id=${device.device_id}`,
      {
        method: "PUT",
        body: JSON.stringify({ uris: [SPOTIFY_URI] }),
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${AUTH_TOKEN}`,
        },
      },
    );
  };

  if (device === null) return null;

  return <button onClick={playCarlyRaeJepsen}>Play Carly Rae Jepsen</button>;
};
```

### `useErrorState`

If an error occurs, an object containing the message will be returned. Otherwise, null is returned.

#### type definition

```ts
type ErrorState = {
  message: string;
  type:
    | "account_error"
    | "authentication_error"
    | "initialization_error"
    | "playback_error";
};

function useErrorState(): ErrorState | null;
```

#### usage

```tsx
const ErrorState = () => {
  const errorState = useErrorState();

  if (errorState === null) return null;

  return <p>Error: {errorState.message}</p>;
};
```

## LICENSE

MIT

## Demo app

A minimal demo app:

https://react-spotify-web-playback-sdk.vercel.app/

A complete demo app:

https://github.com/y-hiraoka/next-spotify-app

---
_Source: https://npm.io/package/react-spotify-web-playback-sdk · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
