---
updatedAt: 2026-07-14T15:15:43.000Z
agentTools:
  projectIndex: https://docs.wistia.com/llms.txt
---

# Channel Embeds

Learn how to set Channel embed options and use the Channel API.

## What is a Channel Embed?

At a high level, a Channel Embed is a snippet of code that lets you put a Wistia Channel on your website.

A Channel Embed displays a collection of episodes (audio or video) in a gallery-style format, and can be split into Sections for better organization. In wide layouts, each Section displays a horizontal row of its episodes. In narrow layouts, each Section displays vertically.

The main view of a Channel--when an episode is not showing--includes a name, description, "Play" button, and a "hero" image or video in the background.

Clicking on a thumbnail will load that episode in the "hero" area. When an episode ends, the next episode in the Channel will automatically start. As it approaches the end, an "Up Next" preview will appear in the lower right. For a full breakdown on Channels, head on over [here](https://wistia.com/support/embed-and-share/channels).

## Channel Embed Types

There are a few different settings that impact how your channel loads and displays.

### Inline

Use an Inline Channel when you want your channel to show within the flow of your website.

#### Responsive Inline

A Responsive Inline Channel will horizontally fill the width of its parent element and grow vertically based on the content of the channel.

This is the preferred inline mode.

#### Fixed Size Inline

A Fixed Size Inline Channel will not grow vertically and has a fixed width. This will make it so that the channel scrolls independently of your website.

### Popover

Use a Popover Channel when you want the viewer to click a "card" which launches your channel so that it covers the full window.

#### Fixed Size Popover

A Fixed Size Popover Channel has a card with a specific width and height that do not change. These are just CSS values; you may change the width and height to work with the CSS of your site.

#### Responsive Popover

A Responsive Popover Channel has a card that will match its width to its immediate parent element, and modify its height to maintain the aspect ratio defined by the Fixed Size values in the Channel Share tab.

If you care about your popover card maintaining a specific aspect ratio, use this type.

## Structure of a Channel Embed Code

A channel embed code is structured similarly to a video's standard embed code. In its most basic form, it looks like this:

```html
<script src="https://fast.wistia.net/assets/external/channel.js" async></script>
<div class="wistia_channel wistia_async_65su5wva44 mode=inline" style="position:relative;"></div>
```

Let's break that down.

The first line is our script, channel.js, which contains the code needed for the initial render of your channel.

The second line is called the "container." It is the DOM element where we will initialize the channel. The `"wistia_channel"` class identifies this DOM element as a channel. The `"wistia_async_65su5wva44"` class says "target the project with ID 65su5wva44 for our channel."

Like video embeds, the `embedOptionName=value` syntax is supported in the class attribute. For the example above, `mode=inline` is set, which means we will render the channel content directly into its container.

The different types of channels all keep this basic form, modifying the embed options, style attribute, or adding responsive wrapper elements.

## Setting complex options

Sometimes embed options can't be passed as simple values. Channels support a syntax similar to video embeds to pass complex options.

```js
window._wcq = window._wcq || [];
window._wcq.push({
  id: "a-string-that-matches-your-channel",
  options: {
    aFunctionForExample: function () {
      doAThing();
    },
  }
});
```

## Routing

When you interact with a Channel Embed, it will change routing information in the URL bar. This makes it so that you can send links to specific videos. It also lets us inject SEO metadata for each video, to be indexed by advanced search engines like Google. You can configure your channel to [use a different routing strategy](#routestrategy) if you like. We use query parameter routing by default because it is highly compatible and also indexable by search engines with no work on your part.

Changing page routing without integrating your site's routing logic can potentially cause issues. Therefore, we support [passing a history object](#history) as an embed option. We plan to provide built-in adapters for the most common client-side routers.

### Deep-linking to a specific episode

Channel routing writes two query parameters as a viewer navigates:

* `wchannelid` - the hashed ID of the open channel
* `wmediaid` - the hashed ID of the episode currently playing

Together, these let you link directly to a specific episode. A viewer who lands on a URL that includes both will open the channel with that episode active.

This works identically in both **inline** and **popover** channels. In each case, selecting an episode adds `wmediaid` to the URL, and the "Copy Link" / thumbnail share options produce a link to that exact episode:

```
https://your-site.com/page?wchannelid=abcde12345&wmediaid=fghij67890
```

A URL with only `wchannelid` (no `wmediaid`) opens the channel on its main view rather than a specific episode. If you expect a per-episode link but only see `wchannelid`, confirm an episode is actually playing - `wmediaid` is added when an episode is open, not when the channel is showing its hero/landing view.

The parameter names and behavior above apply to the default `query-params` route strategy. If you use a different [route strategy](#routestrategy), the same `wchannelid` / `wmediaid` data is read and written through that strategy's format instead.

## Channel Embed Options

A channel's embed options can be set using the `embedOptionName=value` syntax in the container's class attribute, or by using the `window._wcq` object.

You can see how this syntax is used in the [Embed Option documentation for the Player](https://docs.wistia.com/docs/embed-options-and-plugins#using-embed-options). Please note that channels only support embed options listed on this page. They do not support the same options as the player.

### backgroundColor

Set `backgroundColor=ffffff` to change the background color of the embed to white. Defaults to `000000` (black). This option is best used in conjunction with the `foregroundColor` option. To remove the background color entirely, set to `none`.

### color

Set `color=ff0000` to change the highlight color to the hex value for pure red.  Please note that this value should *not* be preceded by a `#`, which is commonly used for CSS color values.

The default value is `54bbff`.

### contentOffsetTop

Set `contentOffsetTop=100` to move the text and video content in a Channel down by 100 pixels.

If you have a fixed position header that appears over your channel, this may be necessary to ensure the header does not block channel and player controls. In that case, you will likely want to pair this with the [pageFixedHeaderHeight](#pagefixedheaderheight) option, e.g. `contentOffsetTop=100 pageFixedHeaderHeight=100`.

The default value is 0.

### customFont

Set `customFont=Walsheim` to change the heading font to Walsheim. If `Walsheim` exists as a CSS font-family on the page, it will be used. If it is not available, the channel embed will fall back to displaying the [googleFont](#googlefont).

Note that font names with spaces must be percent-encoded if they are included as embed options via the class attribute, e.g. `customFont=Slabo%2013px`. You can use our [percent encoding tool](https://docs.wistia.com/docs/embed-options-and-plugins#percent-encoding) to help with that, if necessary.

If you are setting this font to match your brand and expect to have multiple channels, you can paste a snippet like this in the `<head>` of your site:

```html
<script>
  window._wcq = window._wcq || [];
  window._wcq.push({
    id: "_all",
    options: {
      customFont: "Walsheim"
    }
  });
</script>
```

### description

Set `description=My%20channel%20has%20a%0Amulti-line%20description` to change your Channel's description to:

```
My channel has a
multi-line description
```

Remember that spaces in embed option values must be percent encoded, which you can get using `encodeURIComponent("my description")` or by [using our percent encoding tool](https://docs.wistia.com/docs/embed-options-and-plugins#percent-encoding).

### foregroundColor

Set `foregroundColor=000000` to change the foreground color of the embed (for things like text and icons) to black. Defaults to `ffffff` (white). This option is best used in conjunction with the `backgroundColor` option.

### googleFont

Set `googleFont=Roboto` to change the heading font to Roboto. The font name should exactly match the name of the font as it appears in a Google Font's URL. For example, for Open Sans (`https://fonts.google.com/specimen/Open+Sans`), you'd use `googleFont=Open+Sans`.

Note that non-heading sections, like the names of videos in section, cannot be changed currently.

The default value is `Roboto`.

### header

Set `header[on]=true` to turn on the Channel header. Set `header[on]=false` to turn the Channel header off.

### headerFontSizeMultiplier

Set `headerFontSizeMultiplier=1.2` to increase the size of heading fonts by 20% its default. You can use this if your base font is naturally small, or if you want an extra large effect.

The default value is 1.

### history

The `history` option lets you integrate your site's routing mechanism with Wistia Channels. Because it defines functions, it can only be passed using `_wcq`.

```js
window._wcq = window._wcq || [];
window._wcq.push({
  id: "_all",
  options: {
    history: {
      back: function () { ... },
      pushState: function () { ... },
      replaceState: function () { ... },
      state: {
        pointer: 0,
      }
    }
  }
});
```

When you pass a `history` object, we will use this object instead of the `window.history` object to manipulate the page's state. This gives you an opportunity to ensure any history operations work with your client-side routing.

### mode

A channel can have two major modes: inline and popover. Set `mode=inline` to initialize the Channel content directly in the container. Set `mode=popover` to initialize a Channel "preview card" in container, which launches the full channel view on click.

The default value is `popover`.

### noDescription

By default, a Channel has a description that appears in the hero area when not viewing a video. If you'd like to disable this without modifying the text, use `noDescription=true`.

The default value is `false`.

### noHeroCta

A "Play" button appears by default in the hero area when a video is not playing. Set `noHeroCta=true` to remove this button.

The default value is `false`.

### noTitle

By default, a Channel has a title that appears in the hero area when not viewing a video. If you'd like to disable this without modifying the text, use `noTitle=true`.

The default value is `false`.

### overlayZIndex

When a channel sets `mode=popover`, it will launch an overlay that is intended to appear over all other elements on your site. Also, when you launch a video, it appears in another overlay that must be above the channel.

If you find that some elements of your site, such as floating headers or social widgets, appear over your channel, you can set this to a higher value, e.g. `overlayZIndex=100000`. Or if there are certain elements you want to appear on top of it, you can set it to a lower value, e.g. `overlayZIndex=500`.

The default value is 10000.

### playlistLoop

Set `playlistLoop=true` so that, when all a Channel's videos have been played through, it will loop back to the first one.

### resumable

The resumable feature causes videos to pick up where the viewer left off next time they load the page where your video is embedded.

Possible values for the `resumable` embed option are `true`, `false`, and `auto`. This embed option defaults to `auto`.

If `auto`, the resumable feature will only be enabled if the video is 5 minutes or longer, is not autoplay, and is not set to loop at the end. Setting `resumable` to `true` will enable resumable regardless of those factors. `false` disables resumable no matter what.

### routeDataToUrl

A function for use with `routeStrategy=custom`. Refer to `routeStrategy` for example usage.

The `routeData` argument will be an Object that may include `wchannelid` and `wmediaid` properties. If `wchannelid` is set, that channel is open. If `wmediaid` is set, that media is open.

```js
{
  routeDataToUrl: function (currentUrl, routeData) {
    return modifyUrlToIncludeRouteData(currentUrl, routeData);
  }
}
```

### routeStrategy

This option chooses between a few supported methods for reading and writing the URL, as it pertains to Channel routing.

The default value is `query-params`.

#### query-params

This is the default. It will read and write these query params:

* wchannelid
* wmediaid

#### anchor-params

Use `routeStrategy=anchor-params` to set values that look like query params, but they will appear in the page's anchor tag. You can use this if your client-side routing cannot deal with the presence of arbitrary query params, and you do not want to use the `history` object to make it compatible.

Note that setting `routeStrategy=anchor-params` will cause the Channel to not be indexable by search engines like Google.

#### path

Use `routeStrategy=path` to update and parse the URL using friendly paths that appear native to your site. The format looks like:

```
https://wistia.com/my/blog/channel-abcde12345/video-fghij67890
```

That is, the last two path parts, if they begin with `channel-` and `video-`, are used to determine the channel ID and video ID.

NOTE: We may add support for friendly name routing at the end of the URL, e.g.

```
https://wistia.com/my/blog/channel-abcde12345/video-fghij67890/my-cool-video
```

The `routeStrategy=path` option is not compatible with most sites' routing code out of the box, which is why this should only be considered for customers with advanced technical resources. To support this, you will need to add special routing rules. For example:

```
/my/blog/* -> /my/blog
```

Or if you wanted to support Channels with this route strategy site-wide:

```
/(.*?)/channel-(.*) -> $1
```

That is, path parts *past* `/my/blog` should also route to `/my/blog`. This lets our scripts handle the channel routing on the client side.

#### custom

Use `routeStrategy=custom` if you want to have complete control over how routes are interpreted and set. If `routeStrategy=custom` is set, we expect two more functions to be passed as embed options: `routeDataToUrl` and `urlToRouteData`. Because these embed options are functions, they must be passed using `_wcq`.

```js
window._wcq = window._wcq || [];
window._wcq.push({
  id: '_all',
  options: {
    foo: 'bar',
    routeStrategy: 'custom',
    routeDataToUrl: function (currentUrl, routeData) {
      var urlParts = currentUrl.split('?');
      var beforeQueryString = urlParts[0];
      var searchParams = new URLSearchParams(urlParts[1] || '');

      if (routeData.wchannelid) {
        searchParams.set('customChannelParam', routeData.wchannelid);
      } else {
        searchParams.delete('customChannelParam');
      }

      if (routeData.wmediaid) {
        searchParams.set('customVideoParam', routeData.wmediaid);
      } else {
        searchParams.delete('customVideoParam');
      }

      if ('' + searchParams) {
        return beforeQueryString + '?' + searchParams;
      }

      return beforeQueryString;
    },
    urlToRouteData: function (url) {
      var urlParts = url.split('?');
      var searchParams = new URLSearchParams(urlParts[1] || '');
      var result = {};
      var channelParam = searchParams.get('customChannelParam');
      var videoParam = searchParams.get('customVideoParam');
      if (channelParam) {
        result.wchannelid = channelParam;
      }
      if (videoParam) {
        result.wmediaid = videoParam
      }
      return result;
    },
  }
});
```

NOTE: The example above uses URLSearchParams for a simple demonstration, but it is not supported in Internet Explorer. If you use URLSearchParams, make sure you have a [polyfill](https://github.com/jerrybendy/url-search-params-polyfill) for it on your website.

### title

Set `title=My%20Title` to change your Channel's title. Remember that spaces in embed option values must be percent encoded, which you can get using `encodeURIComponent("my description")` or by [using our percent encoding tool](https://docs.wistia.com/docs/embed-options-and-plugins#percent-encoding).

### upNextDisplayDuration

Set `upNextDisplayDuration=5` to have the "Up Next" preview display for 5 seconds, for example, at the end of the video, instead of the default 10 seconds.

### urlToRouteData

A function for use with `routeStrategy=custom`. Refer to `routeStrategy` for example usage.

It should return an Object.

```js
{
  urlToRouteData: function (url) {
    return {
      wchannelid: "abc" // the hashed ID of the channel, if it is open
      wmediaid: "def" // the hashed ID of the media, if it is open
    };
  }
}
```

### videoBackgroundHashedId

Set `videoBackgroundHashedId=myhashedid` to change the background video of your channel to another Wistia video.

The default value is `undefined`.

### videoCardsLayout

A channel can have two different layouts: grid and carousel. Set `videoCardsLayout=grid` to show all thumbnails in a section at once (in a grid format). Set `videoCardsLayout=carousel` to show sections of videos within a single row so that you can scroll through to see all of the videos in the section.

## Channel API Usage

To use the Channel API, you need to get a Channel handle. This can be accomplished using `_wcq`.

```js
window._wcq = window._wcq || [];
window._wcq.push({
  id: "channelid",
  onHasData: function (channel) {
    console.log("this is my channel handle!", channel);
  }
});
```

Or if you just want to play with a channel, you can use the `Wistia.channel(...)` matching function, which has similar semantics to the [Player API Matcher](https://docs.wistia.com/docs/javascript-player-api#wistiaapimatcher). So for example, if I just want to work with the first channel on the page, I can do:

```js
var channel = Wistia.channel();
```

If there are multiple channels on the page, I can target them by their hashed ID or DOM ID:

```js
var channel1 = Wistia.channel("itshashedid");
var channel2 = Wistia.channel("itsdomid");
```

If I want to operate on all the channels on a page, I could do:

```js
Wistia.channel.all().forEach(function (channel) {
  console.log('a channel', channel);
});
```

## Channel API Methods

Wistia Channels currently have a limited public API. Want to do something cool with channels and don't have the tools for it yet? Let us know--it may influence what we make available.

These are the methods that are available now:

### currentVideo()

This will return a [Player API](https://docs.wistia.com/docs/javascript-player-api) handle for the video that is currently visible. If there is no video visible, it returns undefined.

```js
console.log(channel.currentVideo().name());
```

### destroy()

Removes a channel from the DOM and cleans up any lingering global references.

```js
channel.destroy();
```

Note that this will be called automatically within 500ms if a Channel's container has been removed from the DOM. The container's `wistia_channel` class will change to `wistia_channel_destroyed`, which stops it from re-initializing.

### on(eventName, callback)

Lets you respond to [events](#channel-events) triggered by Channels.

Returns a function that unbinds the callback.

```js
var removeEventHandler = channel.on("event", function () {
  console.log("an event happened.");
  removeEventHandler();
});
```

### off(eventName, callback)

Provides another mechanism for unbinding an event handler.

```js
var eventHandler = function () {
  console.log("an event happened.");
  channel.off("event", eventHandler);
};
channel.on("event", eventHandler);
```

## Channel Events

### currentvideochange

Fires when the primary channel video has changed. It passes a reference to the video which can be used to access the Player API.

```js
channel.on("currentvideochange", function (videoId) {
  if (videoId) {
    var video = Wistia.api(videoId);
    console.log("got a handle to the video", video);
  } else {
    console.log("no video is visible");
  }
});
```

### subscribe

Fires when the viewer has entered in their details and clicks "Subscribe" in the Subscribe Modal. You may want to use this if you are doing custom integration work.

```js
channel.on("subscribe", function (data) {
  console.log(data.firstName, data.lastName, data.email, data.visitorKey);
});
```

If you're looking for information entered through a Wistia Form on a video, see the ["conversion" event in our Player API](https://docs.wistia.com/docs/javascript-player-api#conversion).

## WordPress and Other oEmbed Consumers

A Channel's Public URL (`https://fast.wistia.net/embed/channel/the-channel-hashed-id`) serves as its [oEmbed](https://oembed.com) URL, too.

Note that the oEmbed endpoint produces Channel Embeds that are of the "popover" type by default. This is because many oEmbed consumers include a maxwidth and/or maxheight option, which does not play well with our default inline responsive Channel Embed.

You can change from the default by adding `?mode=inline` to the end of the Public URL, but it will always produce a Channel with a maximum width and height, which will cause it to act like a [Fixed Size Inline Channel](#fixed-size-inline) in many situations.

### WordPress

To enable oEmbed support for Wistia, install the [Wistia WordPress Plugin](https://wordpress.org/plugins/wistia-wordpress-oembed-plugin). Pasting the Public URL on a line by itself should then cause WordPress to fetch and preview your Channel.

For better operation with [Responsive Inline Channels](#responsive-inline), your WordPress theme should set a very high maximum embed size by modifying [$content\_width](https://codex.wordpress.org/Content_Width).