Style and Size Wistia Embed Components Safely

Wistia's modern embeds are HTML web components - <wistia-player>, <wistia-form>, <wistia-channel>, and friends. Web components render their internal UI inside a shadow DOM, which is deliberately sealed off from your page's stylesheet. That's what keeps a player looking and behaving the same everywhere it's embedded - but it also means the usual "just target it with CSS" instinct doesn't apply.

This guide covers what you can safely control from your own CSS and embed configuration, what belongs to Wistia's internals and shouldn't be overridden, and how to fix the sizing issues that come up most often.

The mental model: you size the box, Wistia styles the inside

A <wistia-player> behaves like a responsive block element:

It sizes itself to the width of its container and derives its height from the video's aspect ratio.
Its internal layout - controls, poster, letterboxing, the form UI - lives in shadow DOM and is styled by Wistia.

So the reliable division of responsibility is: your CSS controls the element's outer box (width, max-width, aspect ratio, position in your layout). Wistia controls everything inside the shadow boundary. Trying to reach past that boundary is where things go wrong.

What you can safely control

1. Size the element from your own CSS

Style the <wistia-player> element directly - it's a normal element in your document, so width, max-width, and aspect-ratio all work:

<wistia-player media-id="abc123" style="display:block; width:100%; max-width:640px;"></wistia-player>

Or pin an aspect ratio explicitly:

wistia-player {
  display: block;
  width: 100%;
  aspect-ratio: 16 / 9;
}

The player defaults to width: 100% when you don't set a width, and gets its height from the video's aspect ratio. Giving it a clear width to work from is almost always the fix for unexpected sizing.

2. Use the supported layout attributes

The player exposes attributes for the sizing and appearance choices we support directly. The layout-relevant ones:

Attribute	What it does
`aspect`	The video's width-to-height ratio (e.g. `1.7777` for 16:9). The player sizes its height from this.
`fit-strategy`	How the video fills the player box: `contain` (default), `cover`, or `fill`.
`player-color`	The player's accent/controls color (hex, no `#`).
`player-border-radius`	Rounds the player's corners.
`rounded-player`	Applies Wistia's rounded-player styling.

<wistia-player media-id="abc123" aspect="1.7777" fit-strategy="cover" player-color="2949E5"></wistia-player>

Reach for these before you reach for CSS - they're the officially supported way to change how the player looks and fits.

3. Keep the `:not(:defined)` placeholder block

The standard embed code ships with a style block that reserves the correct space before the component finishes loading:

<style>
  wistia-player[media-id='abc123']:not(:defined) {
    background: center / contain no-repeat
      url('https://fast.wistia.com/embed/medias/abc123/swatch');
    display: block;
    padding-top: 56.25%;
  }
</style>

The padding-top: 56.25% reserves a 16:9 box so the layout doesn't jump when the player upgrades. Keep this block. If your embed dropped it, adding it back often resolves load-time layout shift.

What you shouldn't override

The shadow DOM internals — including `:host`

If you inspect a player, you'll see rules like:

:host {
  display: flex;
  position: relative;
  width: 100%;
}

That :host rule lives inside the component's shadow DOM. It's part of the player's own styling, not something in your embed code you can hand-edit - and a :host rule you write from your page's stylesheet generally won't take effect anyway, because it can't reach across the shadow boundary. Don't try to change or remove it. If you're fighting the player's height, the answer is to give the element a width constraint from the outside (see above), not to override its internal display or sizing.

Generated form markup

The <wistia-form> element renders its fields, buttons, and layout from Wistia's own configuration. There's no ::part styling hook and no per-element color control, so you can't recolor individual pieces (like a single button) with page CSS. Use the supported form attributes - form-title, form-button-text, form-lower-text, form-background-color - for the changes we support. Anything beyond those isn't a supported customization.

Common sizing problems

The player collapses to zero height

Symptom: the container shows for a moment, then collapses to 0px - common inside a position: relative; overflow: hidden wrapper in a React/Next.js layout.

Cause: the player doesn't have intrinsic dimensions until it lays itself out, and it sizes from its aspect attribute, not from its parent's height. If you give it height: 100%, that 100% resolves against a parent that has no resolved height yet — so the player computes 0, the auto-height parent follows it down, and everything collapses. (An <img> doesn't hit this because it has natural dimensions; the player doesn't until layout.)

Fix: size from width + aspect ratio, not height. Give the container a real width and let the ratio drive height:

.hero-video {
  position: relative;
  width: 100%;
  max-width: 600px;      /* a real width to resolve against */
}
.hero-video wistia-player {
  display: block;
  width: 100%;
  aspect-ratio: 1 / 1;   /* your target ratio */
}

If you must fill a fixed-height parent, set an explicit height on the parent (not auto) so height: 100% has something to resolve against.

The height balloons

Symptom: the player renders far taller than the video.

Cause: the player has no width constraint to work from, so its width-driven sizing runs away.

Fix: give the element a width or max-width from your CSS, as in "Size the element from your own CSS" above.

When a visual change isn't supported

If the change you want lives inside the shadow DOM (recoloring a single control, restyling generated form markup, editing :host), it's not a supported customization from page CSS, and CSS that appears to work today can break when the component updates. Use the supported attributes and the account-level appearance settings for player look-and-feel. For third-party forms embedded alongside a player (e.g. a Marketo or HubSpot form), that form's markup belongs to the third-party tool, so style it on that tool's side, not through Wistia.

If you're unsure whether something is controllable, the test is simple: is it the element's outer box, or is it inside the shadow DOM? The box is yours; the inside is Wistia's.

Embedding the Aurora Player: Quick Start Guide
iFrame Embed Options
For point-and-click appearance settings (player color, thumbnail, controls), use the Wistia Help Center.