Video Player

The <nys-video> component embeds a YouTube video with a clickable thumbnail, responsive sizing, and accessible playback. The YouTube iframe only loads after the user clicks play, improving page performance.

Note: Only valid YouTube URLs are supported in v1.

Copy Code
<nys-video
  videourl="https://www.youtube.com/watch?v=TBfFzt0150Q"
  titleText="IT'S a Tech Podcast, Episode 3: Human-Centered Design"
></nys-video>

Can't use NYS design System web components in your project? Try using the CSS Variables instead.


Options

Custom Thumbnail

Provide your own thumbnail via the thumbnail property. If not set, the component fetches YouTube's auto-generated thumbnail at: https://img.youtube.com/vi/{video-id}/maxresdefault.jpg

Copy Code
<nys-video
videourl="https://www.youtube.com/watch?v=TBfFzt0150Q"
titleText="IT'S a Tech Podcast, Episode 3: Human-Centered Design
"
thumbnail="https://images.unsplash.com/photo-1518235506717-e1ed3306a89b?q=80&w=2340&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D"
></nys-video>

Autoplay

It is not recommend to use autoplay unless absolutely necessary in specific cases. Please use cautiously.

The iframe loads immediately and plays muted. Sound is always off when autoplay is set — this is intentional and cannot be overridden.

Copy Code
<nys-video
videourl="https://www.youtube.com/watch?v=TBfFzt0150Q"
titleText="IT'S a Tech Podcast, Episode 3: Human-Centered Design"
autoplay
></nys-video>

Disabled

Prevents playback. The thumbnail and play button are visible but non-interactive.

Copy Code
<nys-video
videourl="https://www.youtube.com/watch?v=TBfFzt0150Q"
titleText="IT'S a Tech Podcast, Episode 3: Human-Centered Design"
disabled
></nys-video>

Start Time

Use starttime (in seconds) to begin playback at a specific point.

Copy Code
<nys-video
videourl="https://www.youtube.com/watch?v=TBfFzt0150Q"
titleText="IT'S a Tech Podcast, Episode 3: Human-Centered Design"
starttime="43"
></nys-video>

Sizes

Use explicit sizes to lock a specific layout. If size is not set, the component defaults to size="md".



Copy Code
<nys-video size="full" videourl="https://www.youtube.com/watch?v=TBfFzt0150Q" titleText="Full (width: 100%)"></nys-video>
<nys-video size="md" videourl="https://www.youtube.com/watch?v=TBfFzt0150Q" titleText="Medium (width: 440-675px)"></nys-video>
<nys-video size="sm" videourl="https://www.youtube.com/watch?v=TBfFzt0150Q" titleText="Small (width: 320-439px)"></nys-video>

Usage

When to use this component

  • Use video player when motion or audio communicates something better than text or images alone.

When to consider something else

  • Don't use video if the same message can be delivered clearly with text or a static image.
  • Avoid using video as the only source of key information — always provide a text alternative.

Do

  • Keep titleText to 50–60 characters.
  • Use a clear, high-quality thumbnail so users recognize it as a video.
  • Maintain the default lazy loading for better page performance.
  • Let users choose to start the video; avoid autoplay unless necessary.
  • Reserve space for the 16:9 ratio box to prevent layout shift.

Don't

  • Don't set autoplay without understanding that the video will be muted (nys-video enforces this automatically to protect users from unexpected noise).
  • Don't rely on video alone to convey critical information.

Accessibility

The <nys-video> component includes the following accessibility-focused features:

  • The play button is keyboard focusable and labeled with the video title via aria-label="Play [titleText]".
  • A visually hidden aria-live region announces "Video is playing" or "Advertisement is playing" to screen reader users.
  • titleText is used as both the visible caption and the iframe's title and aria-label — always provide it.

Properties

Property Type Default Description
videourl String — Required. A valid YouTube URL.
titleText String — Caption displayed below (or overlaid on) the video. Also used as the iframe accessible label.
size "full" | "md" | "sm" auto Locks the player to a specific size. If unset, size responds to viewport width.
thumbnail String auto Custom thumbnail URL. Defaults to YouTube's maxresdefault.jpg.
autoplay Boolean false Loads and plays the video immediately, muted.
starttime Number 0 Time in seconds where playback begins.
loading "lazy" | "eager" "lazy" Controls iframe loading behavior after play is triggered.
disabled Boolean false Disables playback interaction.

Style Overrides

The nys-video does not have any css variables because this component must remain consistent across applications and sites.


Events

Suggest a New Component

Do you have an idea for a new NYS Design System web component? Look through the existing proposals in our GitHub discussions board to see if someone already proposed something similar. If not, feel free to submit one.

Edit this page on GitHub (Permissions required)

Last updated: April 2, 2026