HtVideo

Video that plays in the mode set by playback: native controls, a still first frame, or a muted loop.

Use HtImage when the URL can be an image or a video.

#Example

#Usage

#Playback

playback sets how the video plays. In every mode, the video plays inline on iPhone instead of opening fullscreen (playsInline).

#Click

The default click mode shows native controls, and the viewer starts playback. Use it when the video is the content, such as a product walkthrough in a dialog.

#None

The none mode shows the first frame, or poster when set, and never plays. Use it for a thumbnail inside a clickable card, so the card gets the click instead of the native controls.

#Autoplay

The autoplay mode plays the video muted on a loop, with no controls, by default. Use it for a short ambient clip, such as an illustration on a splash page. If the viewer prefers reduced motion, the video shows its first frame instead. For a video the viewer needs to watch, use click, or add controls.

#Controls

controls shows native controls on an autoplaying video, so the viewer can pause it. Use it when the loop carries content, such as a product demo in a chat message. If the viewer prefers reduced motion, the video shows its first frame with the controls, so the viewer can still play it. click always shows controls, and none never does, so controls applies only to autoplay.

#Controls list

controlsList hides parts of the native controls. It takes the native tokens nodownload, nofullscreen, and noremoteplayback, separated by spaces. Chromium browsers support it, and Firefox ignores it. controlsList on MDN lists current support.

#Loop

loop restarts an autoplaying video when it ends. It defaults to true. Set loop={false} for a clip that plays once and stops on its last frame, such as an intro animation.

#Muted

muted starts the video without sound. It defaults to true for autoplay, because browsers block autoplay with sound, and to false for click. Set muted={false} on autoplay only when the viewer opened the video with a click, such as a preview that plays when it opens. Without that click, the browser can refuse to play it, and the video stays on its first frame.

#Native attributes

HtVideo passes through native <video> attributes that it does not own, such as crossOrigin, disablePictureInPicture, and disableRemotePlayback. It owns autoPlay, controls, muted, loop, and playsInline, so set those through playback and its props. See the video element on MDN for the full list.

#Wrapping HtVideo

HtVideoProps is a union, so a plain Omit drops the rules that tie controls and loop to playback="autoplay". Derive a wrapper's props with a distributive Omit to keep it.

#Styling

HtVideo adds no visual styling of its own, apart from a focus ring. Size and frame each video with style props, such as width, maxWidth, borderRadius, and boxShadow. The themed focus ring shows when the video has keyboard focus, including when a dialog focuses it on open. While it shows, it replaces any boxShadow you set.

#Guidelines

#When to use

• Show a video from a URL that is always a video, such as a product walkthrough or a splash page clip.
• Show a video thumbnail that the parent card opens on click, with playback="none".

#When not to use

• For a URL that can be an image or a video, such as an uploaded creative asset — use HtImage instead.
• For a player with custom controls, such as an ad preview with its own play and mute buttons — render a <video> and own its controls.

#Accessibility

• Set aria-label when the video carries information, and say what it shows. Leave it out for an ambient clip that repeats nearby text.
• autoplay follows the viewer's reduced motion setting when the video mounts, so do not add your own check. A change to the setting applies the next time the video mounts.
• A looping video that carries content needs a way to pause it. Use click, or autoplay with controls.

#Props

Inherits all style props, including color, border, and margin props, and the native attributes it does not own.

Name	Default	Description
style	—	ChakraBoxProps["style"]Inline styles, merged with the surface-derived style.
src	—	stringURL of the video.
poster	—	stringURL of an image to show before the video plays.
preload	—	VideoHTMLAttributes<HTMLVideoElement>["preload"]Native hint for how much of the video to load before playback.
playback	"click"	"click" | "none" | "autoplay"How the video plays. - "click": shows native controls, and the viewer starts playback. - "none": shows the first frame, or poster when set, and never plays. The parent handles clicks. - "autoplay": plays muted on a loop by default. Shows the first frame when the viewer prefers reduced motion.
controls	false	booleanShows native controls on an autoplaying video, so the viewer can pause it. Only for autoplay: click always shows controls, and none never does.
loop	true	booleanRestarts the video when it ends. Only for autoplay.
muted	—	booleanStarts the video muted. Defaults to true for autoplay, because browsers block autoplay with sound, and to false for click.
controlsList	—	VideoHTMLAttributes<HTMLVideoElement>["controlsList"]Native controlsList tokens that hide parts of the native controls: nodownload, nofullscreen, noremoteplayback. Applies only while controls show.