# Installation and Usage
## Installation
::: code-group
```bash [npm]
npm install artplayer
```
```bash [yarn]
yarn add artplayer
```
```bash [pnpm]
pnpm add artplayer
```
```bash [bun]
bun add artplayer
```
```html [script]
```
:::
## `CDN`
::: code-group
```bash [jsdelivr.net]
https://cdn.jsdelivr.net/npm/artplayer/dist/artplayer.js
```
```bash [unpkg.com]
https://unpkg.com/artplayer/dist/artplayer.js
```
:::
## Usage
::: code-group
```html [index.html]
ArtPlayer Demo
```
:::
::: warning Note
The player's dimensions depend on the dimensions of its `container`. Therefore, your `container` must have defined dimensions.
:::
::: tip See more usage examples at the following link
[/example](https://github.com/zhw2590582/ArtPlayer/tree/master/example)
:::
## `Vue.js`
::: code-group
```vue [Artplayer.vue]
```
```vue [app.vue]
```
:::
::: warning Artplayer is not reactive:
Directly modifying the `option` in `Vue.js` will not update the player.
:::
## `React.js`
::: code-group
```jsx [Artplayer.jsx]
import Artplayer from 'artplayer'
import { useEffect, useRef } from 'react'
export default function Player({ option, getInstance, ...rest }) {
const $container = useRef()
useEffect(() => {
const art = new Artplayer({
...option,
container: $container.current,
})
if (typeof getInstance === 'function') {
getInstance(art)
}
return () => art.destroy(false)
}, [])
return
}
```
```jsx [app.jsx]
import Artplayer from './Artplayer.jsx'
function App() {
return (
)
}
export default App
```
:::
::: warning Artplayer is not reactive:
Directly modifying the `option` in `React.js` will not update the player.
:::
## TypeScript
The `artplayer.d.ts` file is automatically imported when you import `Artplayer`.
### Vue.js
```vue{3}
```
### React.js
```jsx{2}
import Artplayer from 'artplayer';
const art = useRef(null);
art.current = new Artplayer();
```
### Option
You can also use the type for the options.
```ts{3}
import Artplayer, { type Option } from 'artplayer';
const option: Option = {
container: '.artplayer-app',
url: './assets/sample/video.mp4',
};
option.volume = 0.5;
const art = new Artplayer(option);
```
::: tip Full TypeScript Definitions
[packages/artplayer/types](https://github.com/zhw2590582/ArtPlayer/tree/master/packages/artplayer/types)
:::
## JavaScript
Sometimes your `js` files may lose `TypeScript` type hints. In such cases, you can manually import the types.
Variable:
```js{1-3}
/**
* @type {import("artplayer")}
*/
let art = null;
```
Parameter:
```js{1-3}
/**
* @param {import("artplayer")} art
*/
function getInstance(art) {
//
}
```
Property:
```js{4-6}
export default {
data() {
return {
/**
* @type {import("artplayer")}
*/
art: null,
}
}
}
```
Option:
```js{1-3}
/**
* @type {import("artplayer/types/option").Option}
*/
const option = {
container: '.artplayer-app',
url: './assets/sample/video.mp4',
};
option.volume = 0.5;
const art8 = new Artplayer(option);
```
## Legacy Browsers
The production build `artplayer.js` only supports the latest major version of `Chrome`: `last 1 Chrome version`.
For legacy browsers, you can use the `artplayer.legacy.js` file, which is compatible down to: `IE 11`.
```js
import Artplayer from 'artplayer/legacy'
```
::: code-group
```bash [jsdelivr.net]
https://cdn.jsdelivr.net/npm/artplayer/dist/artplayer.legacy.js
```
```bash [unpkg.com]
https://unpkg.com/artplayer/dist/artplayer.legacy.js
```
:::
::: tip If you need to support even older browsers, modify the following configuration and build it yourself:
Build configuration: [scripts/build.js](https://github.com/zhw2590582/ArtPlayer/blob/master/scripts/build.js#L29)
Reference documentation: [browserslist](https://github.com/browserslist/browserslist#full-list)
:::
## ECMAScript Module
::: tip ESM Demo:
[https://artplayer.org/esm.html](https://artplayer.org/esm.html)
:::
Starting from version `5.2.6`, `artplayer` and all plugins also provide an `ESM` version in `mjs` format, such as:
- `artplayer/dist/artplayer.mjs`
- `artplayer-plugin-danmuku/dist/artplayer-plugin-danmuku.mjs`
```html
ArtPlayer ESM with Import Map
```
## Custom userAgent
Currently, the detection of whether a device is mobile is not always accurate. Sometimes you may want to adjust the player's UI by changing the `userAgent`. Therefore, starting from version `5.2.4`, a global variable `globalThis.CUSTOM_USER_AGENT` has been added.
```html
ArtPlayer Demo
```
::: warning Note
You need to modify it before importing the `Artplayer` dependency for it to take effect.
:::