Wistia Embed Block - Author Guide

The Wistia Embed block adds a Wistia video to the page without slowing it down. Instead of loading the video player right away, it shows your placeholder image with a play button on top. The real video only loads once a visitor clicks play (or presses Enter with the placeholder focused) - nothing extra downloads until then.

There are five ways to add this block:

• Wistia Embed: Just the video, standard width
• Wistia Embed (text-left): Text on the left, video on the right
• Wistia Embed (text-right): Text on the right, video on the left
• Wistia Embed (image-left): Image on the left, video on the right
• Wistia Embed (image-right): Image on the right, video on the left

1. The Standard Block

What you author

Row 1 has two cells:

• Cell 1: The Wistia embed snippet - copy the whole thing from Wistia's Share → Embed panel, <script> tags and all
• Cell 2: The placeholder image visitors see before they hit play

What visitors see

• Your placeholder image, with a small round play button centered on top of it.
• Clicking anywhere on the placeholder (or pressing Enter while it's focused) swaps in the real Wistia player and starts it loading.
• Until someone clicks, the video itself never loads - only your placeholder image does. This keeps the page fast.

Example: Wistia Embed in the Library

That's a standard block capped at 800px wide, with a dark-blue frame showing around it. The max-width and background-color rows are both optional - see the config fields below.

2. Optional Config Fields

Add any of these as extra rows below the content row. Each config row has two cells: the field name in the first cell, the value in the second. All of them are optional - leave a row out entirely and the block uses its default.

• max-width
  • Value: A CSS width, e.g., 800px, 60rem, 50%
  • What it does: Caps how wide the video can grow. Below that width, it still shrinks to fit narrow screens.
  • Default: Full width of the section
• max-height
  • Value: A CSS height, e.g., 450px, 30rem
  • What it does: Caps how tall the video can grow. The video keeps its normal widescreen shape (16:9)—it doesn't stretch or squash.
  • Default: No cap
• padding
  • Value: A single CSS value, e.g., 24px, 1.5rem
  • What it does: Adds even space on all four sides around the video, inside its frame.
  • Default: No padding
• background-color
  • Value: One of the palette names
  • What it does: Fills the space around the video (visible in any padding you add) with a brand color.
  • Default: Transparent
• mobile-first
  • Value: video
  • What it does: Two-column variants only. On phones/narrow screens, shows the video above the text or image instead of below it.
  • Default: Text/image shown first on mobile
• vertical-align
  • Value: top, middle, or bottom
  • What it does: Two-column variants only, and only on desktop/wide screens. Lines up the top of the text/image column against the top, middle, or bottom of the video column. Has no effect on mobile.
  • Default: middle
• video-align
  • Value: left, center, or right
  • What it does: Shifts the video within the space it has to sit in. Only makes a visible difference if you've also set max-width.
  • Default: Video fills the available width, so there's no extra space to shift it into
• wistia-alt
  • Value: A short plain-text description (e.g., Product demo video)
  • What it does: Tells screen readers what to announce when they land on the placeholder and sets the placeholder image's alt text—good for accessibility and SEO.
  • Default: Screen readers just announce "Play video"; the image keeps whatever alt text it already had
• play-button
  • Value: light or dark
  • What it does: Sets the color of the round play button on top of the placeholder. light is a white circle with a blue triangle; dark is a blue circle with a white triangle.
  • Default: light

About video-align: This setting moves the video left, center, or right inside the room it has to move around in. On the standard (full-width) block, the video normally stretches to fill the entire section, so there's no spare space to shift it into - video-align will look like it's doing nothing unless you also add a max-width row to make the video narrower than the section. Once the video is narrower than its space, video-align controls where it sits in the leftover room. The same idea applies on the two-column variants: set max-width on the video's column, and video-align positions it within that half.

About wistia-alt: Describe what the video actually shows, not the fact that it's a video - write "Product demo video," not "Click to play." Keep it short. It's worth adding to every Wistia block since it improves both accessibility and SEO.

About play-button: Pick whichever color stands out better against your placeholder image - dark on pale or light images, light (the default) on dark or busy images. Any value other than dark falls back to the light button.

Example: Wistia Embed w/ Max Width in the Library

Without max-width, the video would fill the whole section and video-align would have nothing to do. With max-width: 720px capping the video's width, video-align: right then pushes that narrower video to the right side of the section instead of the default centered position.

Example: Wistia Embed Two-Column (Image | Video) in the Library

Here wistia-alt gives the placeholder a screen-reader label ("Click to watch Wistia Embed Test 5") and sets the thumbnail's alt text to match. play-button: dark swaps the button to a blue circle with a white triangle, which reads better against this pale product screenshot than the default light button would.

Background color palette

Type the name exactly as shown (lowercase) into the value cell:

• primary: Bright brand blue
• dark: Deep navy blue
• mid: Vivid blue
• accent: Lime/yellow-green
• aqua: Teal
• green: Deep green
• blue: Sky blue
• black: Black
• white: White

If you type a value that isn't on this list, it's simply ignored and no background color is applied.

3. The Two-Column Variants (text-left, text-right, image-left, image-right)

Pick one of these four block names when you want the video paired side-by-side with text or an image:

• text-left - text column on the left, video on the right
• text-right - text column on the right, video on the left
• image-left - image on the left, video on the right
• image-right - image on the right, video on the left

Content model

Row 1 has two cells:

• Cell 1: The text (heading, body copy, button) for text variants—or the image for image variants.
• Cell 2: The Wistia cell: paste both the embed snippet and the placeholder image into this one cell, one after the other.

Optional config rows (from section 2 above) go below row 1, exactly like the standard block.

Layout behavior

• Desktop: The two columns sit side-by-side, each taking half the width, and are vertically centered against each other by default. Add a vertical-align config row (top, middle, or bottom) to change how they line up - handy when your text is much shorter or longer than the video. If you type anything other than those three values, it's ignored and the columns stay centered.
• Mobile / narrow screens: The columns stack, and vertical-align has no effect here since there's no side-by-side alignment to control. By default, your text or image appears first and the video appears below it. If you add mobile-first: video as a config row, the video appears first instead.

Readable text on colored backgrounds

If you set background-color to primary, dark, mid, or green on one of these two-column variants, the heading, body text, and any plain text links in the text/image column automatically switch to white so they stay easy to read against the darker color. You don't need to do anything to turn this on - it happens by itself with those four colors. Button links are left alone and keep their normal button colors. The other palette options (accent, aqua, blue, black, white) don't trigger this - text stays its normal color with those.

Example: Wistia Embed Two-Column (Text | Video) in the Library

Here the text is much shorter than the video, so vertical-align: top lines up the top of the heading with the top of the video instead of leaving it centered against the video's middle. Because background-color is set to primary, the heading text automatically renders white so it's readable against the dark frame.

Example: Wistia Embed Two-Column (Video | Text) in the Library

Here we've set the padding to be much larger than the default by adding padding: 32px which applies to both columns. And we're setting mobile-first: video so that the video appears before the text on mobile devices.

Example: Wistia Embed Two-Column (Image | Video) in the Library

Here the photo is authored in the first cell, and the video (embed + thumbnail together) is authored in the second cell.

Example: Wistia Embed Two-Column (Video | Image) in the Library

Here the video (embed + thumbnail together) is authored in cell 1 and the photo in cell 2 - but because this is the image-right variant, the photo visually renders on the right and the video on the left. You can change the rendering order on mobile with mobile-first: video

Authoring Checklist

• Choose the right block name for the layout you want (standard, text-left, text-right, image-left, or image-right).
• Copy the entire Wistia embed snippet from Wistia's Share → Embed panel - don't trim any of the <script> tags.
• Always include a placeholder/thumbnail image - without one, the play button and click-to-load behavior won't appear.
• For the two-column variants, paste the embed snippet and the placeholder image into the same cell (the Wistia cell); put your text or image in the other cell.
• Add any config rows (max-width, max-height, padding, background-color, mobile-first, vertical-align, video-align, wistia-alt, play-button) below the content row - only include the ones you actually need.
• Add a wistia-alt row describing what the video shows - do this for every video, for accessibility and SEO.
• Double-check background-color values against the palette list; anything else is silently ignored.
• If you want video-align to actually move the video, make sure you've also set max-width - otherwise the video fills the space and there's nowhere for it to shift to.
• If the default light play button is hard to see against your placeholder image, add play-button: dark.
• Preview the page and click the placeholder to confirm the video actually loads and plays.
• For two-column variants, preview on both desktop and mobile to confirm the stacking order looks right, and check vertical-align on desktop if your text and video are noticeably different heights.

Support Tips

• Video won't play when clicked: Confirm the embed snippet cell still has the full script tags - a partially copied snippet won't load.
• No play button showing: Make sure a placeholder image is present in the block; the play button is added on top of it, so without an image there's nothing to click.
• Background color not showing: Check the spelling of the value against the palette list above (primary, dark, mid, accent, aqua, green, blue, black, white) - it must match exactly, and you'll only see it if you've also set padding or the video hasn't filled the full frame.
• Video looks squished or too tall: If you've set max-height, remember the video keeps its widescreen shape - letterboxing (background color showing at the sides) is expected rather than stretching.
• Text and video in the wrong order on mobile: By default, text/image comes first and video comes second on small screens. Add a mobile-first row with the value video to flip that order.
• Video appears on the wrong side: For the two-column variants, cell order in the table stays the same (content first, Wistia cell second) - the block name (text-left vs. text-right, image-left vs. image-right) is what controls which side the video visually lands on, not the order you paste things in.
• vertical-align doesn't seem to do anything: This only applies to the two-column variants (text-left, text-right, image-left, image-right), and only on desktop/wide screens - on mobile the columns stack, so there's no side-by-side alignment to adjust. Also double-check the value is exactly top, middle, or bottom; anything else is ignored and defaults to middle.
• video-align doesn't seem to do anything: This is the most common one - video-align only has something to do once the video is narrower than the space around it. Add a max-width row to shrink the video, and video-align will then shift it left, center, or right within the leftover space.
• Screen readers just say "Play video" with no detail: Add a wistia-alt row with a short description of what the video shows - this also becomes the placeholder image's alt text.
• Play button is hard to see against the placeholder image: Add a play-button row set to dark for pale or light images, or leave it unset (or set it to anything other than dark) to keep the default light button for dark or busy images.
• Text isn't turning white on a colored background: The automatic white text only kicks in on the two-column variants when background-color is primary, dark, mid, or green. The other palette colors (accent, aqua, blue, black, white) don't change the text color, and buttons always keep their own colors regardless of background.