# Customize the look and feel of Mux Player
Learn how to customize the look and feel of Mux Player to fit your brand and use case.
Mux Player is a fully-featured player out of the box that is made to look good and be fully functional and responsive for different screen sized. You can customize things on Mux Player like the colors and which controls are showing up.

If you want to go further with customization on things like icons, breakpoints, or where controls are shown, you will want to go down the path of using a [different theme or creating your own theme](/docs/guides/player-themes).

## Customize the poster image

By default Mux Player will pull the default poster image from the middle of the video based on the Playback ID that you provide. The default poster image is the mid-point of the Mux asset.

`https://image.mux.com/{PLAYBACK_ID}/thumbnail.jpg`

If you want to change the poster image, you have two options:

1. Pass in `thumbnail-time` (React: `thumbnailTime`) with the value in seconds of the thumbnail that you want to pull from the video.

   * The `thumbnail-time` attribute (React: `thumbnailTime`) are only available if you're NOT using [Signed URLs.](/docs/guides/secure-video-playback)
   * If you *are* using Signed URLs you'll need to add the `time=` parameter to your signed token (see the [Usage with signed URLs](/docs/guides/player-advanced-usage) guide).

2. Use the `poster=` attribute.
   * You can set any arbitrary image URL the same way you would do with the HTML5 `<video>` element. For the best viewer experience, your poster image should match the aspect ratio of the video.

### Provide a placeholder while the poster image loads

While the poster image loads, Mux Player will display the contents of the `placeholder=` attribute. Consider using a [Data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs) so that the placeholder is immediately available without a network request.

Mux Player [embedded in an iframe through player.mux.com](/docs/guides/player-integrate-in-your-webapp#embed) will automatically generate a Data URL placeholder for you.

If you are generating your pages with a Node.js server (like [Next.js](https://nextjs.org/docs/app/getting-started/fetching-data)), you can generate Data URLs for Mux Videos with the `@mux/blurup` package.

The Data URLs generated by `@mux/blurup` contain lightweight multicolor gradients that visually represent what the default poster image will look like once it has fully loaded.

For example:

<MultiImage
  images={[
  { src: "/docs/images/blurup-loading.png", width: 409, height: 230 },
  { src: "/docs/images/blurup-loaded.png", width: 409, height: 227 },
]}
/>

```js
// Server-Side
import { createBlurUp } from '@mux/blurup';

const options = {};
const muxPlaybackId = 'O6LdRc0112FEJXH00bGsN9Q31yu5EIVHTgjTKRkKtEq1k';

const getPlaceholder() = async () => {
  const { blurDataURL, aspectRatio } = await createBlurUp(muxPlaybackId, options);
  console.log(blurDataURL, aspectRatio);
  // data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" width="100%" ...
};
```

```html
<!-- Client-Side -->
<mux-player
  playback-id="{playbackId}"
  placeholder="{blurDataUrl}"
  style="aspect-ratio: {aspectRatio}"
></mux-player>
```

If you change the thumbnail time with `thumbnailTime`, you should also pass a time configuration to `createBlurUp(playbackId, { time: customThumbTime })` to generate the correct placeholder.

You can learn more about `@mux/blurup` [on GitHub](https://www.github.com/muxinc/blurup).

If you have a client-side-only application and you *can't* generate a blur placeholder, you might want to pass a smaller resolution poster image URL as the placeholder value that will load more quickly than the final hi-res poster.

This placeholder is provided for you if you're using Mux Player in an iframe through player.mux.com.

## Add a video title

Use the `title` attribute to add a title in the top left corner on Mux Player. This title is visible when the player is wide enough to accommodate it. Note that this is different that `metadata-video-title`, which is a Mux Data metadata field.

Sandpack interactive code example configuration JSON.stringified:
```json
{
  "customSetup": {
    "dependencies": {
      "@mux/mux-player": "latest"
    }
  },
  "files": {
    "/index.html": {
      "code": "<mux-player\nplayback-id=\"a4nOgmxGWg6gULfcBbAa00gXyfcwPnAFldF8RdsNyk8M\"\ntitle=\"My awesome video\"\nmetadata-video-title=\"Test video title\"\nmetadata-viewer-user-id=\"user-id-007\"\nstyle=\"aspect-ratio: 16/9; width: 100%;\"\n></mux-player>\n\n<!-- or, embed the player with an iframe -->\n\n<iframe\n  src=\"https://player.mux.com/a4nOgmxGWg6gULfcBbAa00gXyfcwPnAFldF8RdsNyk8M?title=My%20awesome%20video&metadata-video-title=Test%20video%20title&metadata-viewer-user-id=user-id-007\"\n  style=\"aspect-ratio: 16/9; width: 100%; border: 0;\"\n  allow=\"accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;\"\n  allowfullscreen=\"true\"\n></iframe>",
      "active": true
    },
    "/index.js": {
      "code": "import '@mux/mux-player'",
      "hidden": true
    }
  },
  "stacked": true
}
```

## Style with CSS

The Mux Player Web Component can be styled and positioned with CSS just like you would any other HTML element. For example:

```css
mux-player {
  width: 100%;
  max-width: 800px;
  margin: 40px auto;
}
```

In React, you can style the `<MuxPlayer>` component the same way you style other components; with [styled-components](https://styled-components.com/) or directly with the `style=` prop.

<Callout type="warning">
  You can not style Mux Player with CSS if you are using the HTML embed through player.mux.com.
</Callout>

### Aspect ratio

<ApiRefLink href="/docs/api-reference/video/assets/get-asset">The Mux API</ApiRefLink> will provide you the aspect ratio of your video in the form of `w:h`. You should save this `aspect_ratio` in your database or CMS alongside the `playback_id` and other asset details. Then you can use that with CSS in the form of `w / h`. This is using [the CSS aspect-ratio property](https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio) which is supported in all evergreen browsers.

Setting the aspect ratio of the player is important for preventing [Cumulative Layout Shift](https://web.dev/cls/) on the page.

```css
mux-player {
  aspect-ratio: 16 / 9;
}
{/* or if you're using the iframe embed */}
iframe {
  aspect-ratio: 16 / 9;
}
```

### Rounded corners

You can add rounded corners to the player by wrapping it in a `div` with the `style` attribute set to `border-radius`.

```html
<div style="border-radius: 10px; overflow: hidden; display: flex;">
  <mux-player></mux-player>
</div>
```

### Video size and position

You can change the way that video is sized within its `<video>` element. Mux Player provides two css variables that you can use to override the standard `object-fit` and `object-position` [css properties](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit).

```css
mux-player {
  --media-object-fit: cover;
  --media-object-position: center;
}
```

<Callout type="warning">
  When using the player.mux.com iframe embed, you can not use CSS to style mux-player directly, so you won't have access to these CSS Custom Properties.
</Callout>

## Hiding controls with CSS

By default, Mux Player will show all the controls associated with the current player size and stream type.

To hide certain controls, use CSS variables like this:
`--seek-backward-button` will control the `display` of the seek backward button. Set it to `none` to hide it completely.

```css
mux-player {
  --seek-backward-button: none;
  --seek-forward-button: none;
}
```

CSS vars can also be passed inline

```html
<mux-player
  style="--seek-backward-button: none; --seek-forward-button: none;"
></mux-player>
```

<Callout type="player.mux.com warning">
  When using the iframe embed, you can not use CSS to style mux-player directly, so you won't have access to these CSS Custom Properties.
</Callout>

### Controls sections

You can target specific sections of the player by prefixing the CSS vars with the section. The following sections are available:

* `top` the top control bar that shows on the small player size
* `center` the center controls that show the seek forward/backward button and play button
* `bottom` the bottom control bar

```html
<mux-player
  style="--center-controls: none; --top-captions-button: none;"
></mux-player>
```

### Available CSS variables

The below CSS selector shows all available CSS vars for hiding, each one can be prefixed with a section.

```css
mux-player {
  /* Hide all controls at once */
  --controls: none;

  /* Hide the error dialog */
  --dialog: none;

  /* Hide the loading indicator */
  --loading-indicator: none;

  /* Target all sections by excluding the section prefix */
  --play-button: none;
  --live-button: none;
  --seek-backward-button: none;
  --seek-forward-button: none;
  --mute-button: none;
  --captions-button: none;
  --airplay-button: none;
  --pip-button: none;
  --fullscreen-button: none;
  --cast-button: none;
  --playback-rate-button: none;
  --volume-range: none;
  --time-range: none;
  --time-display: none;
  --duration-display: none;
  --rendition-menu-button: none;

  /* Target a specific section by prefixing the CSS var with (top|center|bottom) */
  --center-controls: none;
  --bottom-play-button: none;
}
```

### Controls Backdrop Color

Mux Player exposes a CSS variable (`--controls-backdrop-color`) to set the controls backdrop color.
This is the background color that will show up behind the controls in the player.

```css
mux-player {
  --controls-backdrop-color: rgb(0 0 0 / 60%);
}
```

The backdrop color is turned off by default. Note if you change this color be sure to make the contrast against the controls high enough as it has implications on the accessibility of the controls as they may not meet [the contrast ratio requirements for WCAG 2.1](https://www.w3.org/TR/WCAG/#contrast-minimum).

### CSS Parts

Mux Player uses a [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) to encapsulate its styles and behaviors. As a result, it's not possible to target its internals with the usual CSS selectors. Instead, some components expose parts that can be targeted with the [CSS part selector](https://developer.mozilla.org/en-US/docs/Web/CSS/::part), or `::part()`.

```html
<style>
  mux-player::part(center play button) {
    display: none;
  }
</style>
<mux-player playback-id="DS00Spx1CV902MCtPj5WknGlR102V5HFkDe"></mux-player>
```

Supported parts: `live`, `layer`, `media-layer`, `poster-layer`, `vertical-layer`, `centered-layer`, `gesture-layer`, `top`, `center`, `bottom`, `play`, `button`, `seek-backward`, `seek-forward`, `mute`, `captions`, `airplay`, `pip`, `cast`, `fullscreen`, `playback-rate`, `volume`, `range`, `time`, `display`.

CSS parts allow you to style each element individually with a selector like `::part(center play button)` or target multiple elements if the part is assigned to multiple elements internally, usage `::part(button)`. Every CSS property can be declared in the selector, this makes it a very powerful API.

Note that if you are using advanced styling with `::parts` selectors then be sure to test out your custom styles when upgrading to new versions of Mux Player.

## Provide color variables

The colors of Mux Player can be customized with the following options:

| HTML Attribute | React Prop | Description |
| ------------- | ---------- | ----------- |
| `accent-color` | `accentColor` | Changes the color used to accent the controls |
| `primary-color` | `primaryColor` | Changes the color of the control icons |
| `secondary-color` | `secondaryColor` | Sets the background color of the control bar |

<Callout type="warning">
  When using the iframe embed, you can not use CSS to style mux-player directly, so you won't have access to these CSS Custom Properties.
</Callout>

### HTML element example

Sandpack interactive code example configuration JSON.stringified:
```json
{
  "customSetup": {
    "dependencies": {
      "@mux/mux-player": "latest"
    }
  },
  "files": {
    "/index.html": {
      "code": "<mux-player\nplayback-id=\"a4nOgmxGWg6gULfcBbAa00gXyfcwPnAFldF8RdsNyk8M\"\nmetadata-video-title=\"Test video title\"\nmetadata-viewer-user-id=\"user-id-007\"\naccent-color=\"#f97316\"\n></mux-player>",
      "active": true
    },
    "/index.js": {
      "code": "import '@mux/mux-player'",
      "hidden": true
    }
  }
}
```

### React example

Sandpack interactive code example configuration JSON.stringified:
```json
{
  "customSetup": {
    "dependencies": {
      "@mux/mux-player-react": "latest"
    }
  },
  "files": {
    "/App.js": {
      "code": "import MuxPlayer from \"@mux/mux-player-react\"; \n\nexport default function App() {\n  return (\n    <MuxPlayer\n      playbackId=\"a4nOgmxGWg6gULfcBbAa00gXyfcwPnAFldF8RdsNyk8M\"\n      metadata={{\n        video_id: \"video-id-54321\",\n        video_title: \"Test video title\",\n        viewer_user_id: \"user-id-007\",\n      }}\n      accentColor=\"#f97316\"\n    />\n  );\n}\n",
      "active": true
    },
    "/src/index.js": {
      "code": "",
      "hidden": true
    }
  },
  "template": "react"
}
```

## Change default behavior

Below are the attributes (Web Component) / props (React) available to enable, disable, hide, or change aspects of various controls to suit your use case.

### Mute

While Mux Player defaults to enabling sound, you can pass an attribute/prop to start playback muted.

`muted` is a boolean value that, when `true`, defaults sound to a muted state. Users can still unmute and manage volume as desired.

### Skip forward/backward

The amount of time for skip forward/backward defaults to 10 seconds. This can be changed by passing the following attributes (HTML element) / props (React), which updates both the seek buttons and keyboard ("hotkey") behaviors.

| Attribute (HTML) | React Prop | Description | Example |
| --------------- | ---------- | ----------- | ------- |
| `forward-seek-offset` | `forwardSeekOffset` | Sets the number of seconds to skip forward | `forward-seek-offset="5"` will apply a 5 second skip forward |
| `backward-seek-offset` | `backwardSeekOffset` | Sets the number of seconds to skip backward | `backward-seek-offset="5"` will apply a 5 second skip backward |

### Closed captions

When captions are available on an asset, we show the control for them and enable their appearance by default.

You can opt to disable their appearance (while still showing the control) by using the `default-hidden-captions` (HTML element & embed) attribute or `defaultHiddenCaptions` (React) prop and a boolean value.

### Start time

If you'd like to set a specific time stamp as the start of playback for an asset, you can use the `start-time` (HTML element & embed) attribute or `startTime` (React) prop and a time value.

When `start-time` is provided, it will also be used for the `thumbnail-time` if no `thumbnail-time` is explicitly provided.

Example: `start-time="13"` will begin playback at 13 seconds into the asset.

### Looping content

You can automatically loop the asset once playback completes with the `loop` attribute and a boolean value.

If you have a background looping video on your page for example, you might want to: turn off all controls, autoplay, mute and loop the video:

```html
<style>
  mux-player {
    --controls: none;
  }
</style>

<mux-player
  playback-id="23s11nz72DsoN657h4314PjKKjsF2JG33eBQQt6B95I"
  autoplay="muted"
  loop
></mux-player>
```

<Callout type="warning">
  When using the iframe embed, you can not use CSS to style mux-player directly, so you won't have access to the `--controls` CSS Custom Properties.
</Callout>

## Autoplay

Autoplay in browsers is a difficult beast. See [this doc](/docs/guides/web-autoplay-your-videos) if you're curious about the details. The good news is that Mux Player can help you handle autoplay when it is warranted.

Before you decide to autoplay your assets, first ask yourself: *Is this necessary?* Often times it negatively impacts accessibility, and many viewers find autoplay to be an impediment to their experience.

Here are your options for autoplay:

| Attribute (HTML & embed) | Prop (React) | Description | Behavior |
| --------------- | ------------ | ----------- | -------- |
| `autoplay` | `autoPlay` | Basic autoplay | Will try to autoplay with sound on (likely to fail) |
| `autoplay="muted"` | `autoPlay="muted"` | Muted autoplay | Will autoplay the video in muted state (likely to work) |
| `autoplay="any"` | `autoPlay="any"` | Fallback autoplay | Will try autoplay with sound first, then fall back to muted if that fails |

## Keyboard shortcuts

By default, Mux Player has several keyboard shortcuts, or hotkeys, enabled. These hotkeys will only function if the player or one of the player controls are focused.

### Default hotkeys

| Key   | Name to turn off | Behavior                        |
| ----- | ---------------- | ------------------------------- |
| Space | `nospace`        | Toggle Playback                 |
| `c`   | `noc`            | Toggle captions/subtitles track |
| `k`   | `nok`            | Toggle Playback                 |
| `m`   | `nom`            | Toggle mute                     |
| `f`   | `nof`            | Toggle fullscreen               |
| ⬅️    | `noarrowleft`    | Seek back 10s                   |
| ➡️    | `noarrowright`   | Seek forward 10s                |

### Turning hotkeys off

You can turn off all hotkeys or individual ones.

#### Turning all hotkeys off

To turn all hotkeys off, add the `nohotkeys` attribute to the Mux Player element:

```html
<mux-player
  nohotkeys
  playback-id="EcHgOK9coz5K4rjSwOkoE7Y7O01201YMIC200RI6lNxnhs"
  metadata-video-title="Test video title"
  metadata-viewer-user-id="user-id-007"
></mux-player>
<!-- or for the embed... -->
 <iframe
  src="https://player.mux.com/EcHgOK9coz5K4rjSwOkoE7Y7O01201YMIC200RI6lNxnhs?nohotkeys=true
  style="aspect-ratio: 16/9; width: 100%; border: 0;"
  allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
  allowfullscreen="true"
></iframe>
```

With the Mux Player Web Component or React component can also do it via JavaScript:

```js
const player = document.querySelector("mux-player");
// disable all hotkeys
player.nohotkeys = true;

// re-enable all hotkeys
player.nohotkeys = false;
```

#### Turning off specific hotkeys

If you only want to turn off specific hotkeys, you can do so via JavaScript or HTML.

Using the "Name to turn off" above, you can add those to a `hotkey` attribute to turn off the specific hotkeys you don't want enabled.

For example, to turn off seeking with the arrow keys:

```html
<mux-player
  hotkeys="noarrowleft noarrowright"
  playback-id="EcHgOK9coz5K4rjSwOkoE7Y7O01201YMIC200RI6lNxnhs"
  metadata-video-title="Test video title"
  metadata-viewer-user-id="user-id-007"
></mux-player>
<!-- or for the embed... -->
 <iframe
  src="https://player.mux.com/EcHgOK9coz5K4rjSwOkoE7Y7O01201YMIC200RI6lNxnhs?hotkeys=noarrowleft%20noarrowright"
  style="aspect-ratio: 16/9; width: 100%; border: 0;"
  allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
  allowfullscreen="true"
/></iframe>
```

If you're using the Mux Player Web Component or React component, you can also do this programmatically via the `hotkeys` property on the element. This provides a [DOM Token List](https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList), a la [classList](https://developer.mozilla.org/en-US/docs/Web/API/Element/classList), that allows you to add or remove each key.

```jsx
const player = document.querySelector("mux-player");

// turn off seeking with the arrow keys
player.hotkeys.add("noarrowright", "noarrowleft");

// re-enable the arrow keys
player.hotkeys.remove("noarrowright", "noarrowleft");
```

## Styling captions

Although the `::cue` CSS selector/psuedo-element exists and has good [browser support](https://developer.mozilla.org/en-US/docs/Web/CSS/::cue) on paper, actual support of individual CSS properties when combined with it is very inconsistent. FireFox particularly doesn't support many of them.

There are two unique CSS properties that you can use to do very basic styling of the captions text though. Combined with the `::part()` selector we can apply them like this:

```css
mux-player::part(media-layer) {
  -webkit-text-fill-color: red;
  -webkit-text-stroke: 1px blue;
}
```

Despite being `-webkit-` prefixed, these have good cross-browser support.

Broader and more advanced support for caption styling will be available in a future version of the player.

<Callout type="warning">
  You can not style the Mux Player element with CSS if you are using the HTML embed through player.mux.com.
</Callout>