HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
Video PlaylistView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA list of video clips that play one after another in a single player.StableSince 0.1.0MediaUsageimport'@fusion.dev/helix/video-playlist'import'@fusion.dev/helix-headless/video-playlist'Preview
API ReferenceRoothelix-video-playlistA list of video clips that play one after another in a single player.
PropTypeDescriptionactivestringThe value of the current item.canceledLabelstringDefault"Canceled"What screen readers hear when a move is put back, in a reorderable
playlist. {name} is the entry's words.defaultActivestringDefault""The value of the item declared current in markup.droppedLabelstringDefault"Dropped"What screen readers hear when a moved entry is let go, in a reorderable
playlist. {name} is the entry's words.emptyLabelstringDefault"No videos"What the playlist says while it has no entries. The empty slot replaces it.labelstringDefault"Playlist"The list's name, read by screen readers.movedLabelstringDefault"{name} moved to position {position} of {count}"What screen readers hear each time a key moves an entry, in a
reorderable playlist. {name} is the entry's words, {position} its
new place, counting from 1, and {count} the number of entries.noAdvancebooleanDefaultfalseStays on an entry when its clip ends, where the playlist would otherwise
play the next one. The player's controls, a press, and next() still
move. repeat="one" still plays the entry again.pickedUpLabelstringDefault"Picked up {name}"What screen readers hear when a pointer picks up an entry, in a
reorderable playlist. {name} is the entry's words.playingLabelstringDefault"Now playing {title}"What the live region says when the playlist moves to another entry.
{title} is the entry's name.reorderablebooleanDefaultfalseLets a reader move the entries, with Alt and the arrow keys or by
dragging one. The playlist moves no entry itself: you move your entries
on helix-reorder.repeat"all"|"one"What happens when an entry ends with no next one to go to. one plays the
same entry again, and all goes from the last entry back to the first.
Absent, the playlist stops on the last entry and sends helix-end.shufflebooleanDefaultfalseWhether the entries play in a random order. The order starts from the
entry that is current, and holds until shuffle is turned off or an entry
arrives or leaves, so previous goes back through what has played.
ReadTypeDescriptioncurrentEntryHelixHeadlessVideoPlaylistItemThe entry that is current, with the src, poster, value and name the
player was given, or undefined in an empty playlist.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The entries.emptyShown while the playlist has no entries. Defaults to empty-label.playerThe player that plays the entries.
EventTypeDescriptionhelix-activateHelixActivateEventThe current entry changed. The playlist already holds the new entry when this is sent, and detail.previous is the entry it left. currentEntry is the entry itself, with its src, poster and name.helix-before-activateHelixBeforeActivateEventThe current entry is about to change, and detail.cause says why: press, next, previous, ended, or removed. Cancelable: cancel it to keep the current entry.helix-before-reorderHelixBeforeReorderEventAn entry was moved to a new place, in a reorderable playlist, with every entry's value in the new order in detail.keys. Cancelable: cancel it to keep the entry where it is.helix-endHelixEndEventThe last entry finished playing, and the playlist stopped there. Not sent while repeat is set.helix-reorderHelixReorderEventFired after helix-before-reorder when nobody canceled it. Move your entries to the order in keys. Cancelable: cancel it to say the move did not happen.
MethodTypeDescriptionnext() => voidMoves to the next entry and plays it, as the player's next control does.
Follows shuffle, goes round under repeat="all", and stays on the last
entry otherwise.previous() => voidMoves to the previous entry and plays it, as the player's previous control
does. Under shuffle it goes back through the order that played.requestActive(next: string, cause: string) => booleanRequests a new current item, and returns whether the change was applied.
PartDescriptionemptyThe box that holds the empty slot, drawn while there are no entries.itemsThe list of entries.liveA live region that says which entry plays after the playlist moves. Visually hidden in the styled tier.playerThe region that holds the player.
CSS PropertyDescription--video-playlist-empty-colorThe color of the words shown while there are no entries.--video-playlist-empty-paddingThe space around the words shown while there are no entries.--video-playlist-gapThe space between the player and the list.--video-playlist-items-gapThe space between the entries.--video-playlist-layoutThe grid columns for the player and the list.--video-playlist-sizeThe height the list reaches before it scrolls.
Custom stateDescriptionendedThe last entry finished and the playlist stopped there, until an entry plays again.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Itemhelix-video-playlist-itemOne entry in a video playlist.
PropTypeDescriptioncurrentbooleanDefaultfalseWhether this entry is the one playing.disabledbooleanDefaultfalsePrevents the entry from being chosen.focusablebooleanWhether the entry holds the playlist's tab stop. Unset, every entry is in
the tab order, which is what a server renders.posterstringDefault""The image shown before this entry plays, also used as the row's thumbnail.srcstringDefault""The file this entry plays.valuestringDefault""The entry's identifier, compared against the playlist's active.
ReadTypeDescriptiontextstringThe entry's name: its own text, without the content in its named slots.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The entry's name.indicatorA mark shown on the entry that is playing, such as an equalizer icon. Rendered only while the entry is current.mediaA thumbnail. Defaults to an image of poster.metaContent after the name, such as a duration or a date.
EventTypeDescriptionhelix-selectHelixSelectEventThe entry was chosen. Cancelable: cancel it to keep the current entry.
MethodTypeDescriptionfocus(options: FocusOptions) => voidFocuses the entry's button, which is where the playlist's arrow keys send
focus. The host itself takes no focus.
PartDescriptioncontainerThe list item that holds the button.indicatorThe indicator slot, at the end of the row, rendered only while the entry is playing. It draws no box until you give it one.itemThe row, which is a button.item-currentAdded to item for the entry that is playing.labelThe name and the content after it.mediaThe column at the start of the row.thumbnailThe image of poster, shown when the media slot is empty.
CSS PropertyDescription--video-playlist-item-background-colorThe fill behind a row.--video-playlist-item-colorThe color of an entry's name.--video-playlist-item-current-background-colorThe fill behind the entry that is playing.--video-playlist-item-current-mark-colorThe color of the bar beside the entry that is playing.--video-playlist-item-gapThe space between the thumbnail and the name.--video-playlist-item-hover-background-colorThe fill behind a row under the pointer.--video-playlist-item-meta-colorThe color of the content in the meta slot.--video-playlist-item-padding-blockThe space above and below a row's content.--video-playlist-item-padding-inline-endThe space after a row's content.--video-playlist-item-padding-inline-startThe space before a row's content, where the bar beside the playing entry sits.--video-playlist-item-radiusThe corner radius of a row.--video-playlist-media-aspect-ratioThe shape of the thumbnail column.--video-playlist-media-radiusThe corner radius of the thumbnail.--video-playlist-media-sizeThe width of the thumbnail column.
Custom stateDescriptioncurrentThe entry that is playing.draggingThe entry a pointer is dragging, in a reorderable playlist.drop-afterThe entry the dragged one would land after, which the drop indicator is drawn under.drop-beforeThe entry the dragged one would land before, which the drop indicator is drawn over.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Menuhelix-video-playlist-menuThe playlist's entries, as a menu inside the player's control bar.
PropTypeDescriptionlabelstringDefault"Episodes"The name of the menu and its trigger, read by screen readers.placement"bottom"|"bottom-end"|"bottom-start"|"left"|"left-end"|"left-start"|"right"|"right-end"|"right-start"|"top"|"top-end"|"top-start"Default"top-end"Where the menu opens relative to its trigger.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescriptiontriggerReplaces the button that opens the menu.
EventTypeDescriptionhelix-selectHelixSelectEventAn entry was chosen. The event carries its value, and the playlist listens for it. Cancelable: cancel it to keep the current entry.
PartDescriptionentryOne entry in the menu.entry-endThe column at the end of an entry, which holds its shortcut. It is always present.entry-itemThe entry's row. It is an <a> when href is set.entry-markThe mark at the end of an entry: a check mark when it is checked, or a caret when it opens a submenu.entry-shortcutThe key drawn for an entry's shortcut. The playlist's entries set none.entry-shortcut-kbdThe key inside entry-shortcut.entry-shortcut-keyOne key of an entry's shortcut chord, inside entry-shortcut. The playlist's entries set none.entry-shortcut-separatorThe + between two keys of an entry's shortcut, where the platform writes one.entry-startThe column at the start of an entry. It is a slot and is always present.entry-surfaceThe panel an entry's submenu opens in beside it. The playlist's entries have none.menuThe menu that holds the entries.menu-backThe button that goes back from a submenu.menu-back-markThe icon on a submenu's back button.menu-emptyShown when there are no items to show.menu-headerThe bar above a submenu, holding the back button and the submenu's name.menu-liveThe inner menu's live part, the region screen readers announce its empty and loading messages from.menu-loadingShown while the items are loading.menu-search-fieldThe inner menu's filter field, drawn with filterable.menu-surfaceThe floating panel the menu is drawn on.menu-titleThe name of the submenu that is shown.posterAn entry's poster image, if it has one.triggerThe button that opens the menu.
CSS PropertyDescription--video-playlist-menu-colorThe color of the trigger. Defaults to the control bar's color.--video-playlist-menu-posterThe width of an entry's poster image.--video-playlist-menu-sizeThe size of the trigger's icon.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-video-playlistA list of video clips that play one after another in a single player.
PropTypeDescriptionactivestringThe value of the current item.canceledLabelstringDefault"Canceled"What screen readers hear when a move is put back, in a reorderable
playlist. {name} is the entry's words.defaultActivestringDefault""The value of the item declared current in markup.droppedLabelstringDefault"Dropped"What screen readers hear when a moved entry is let go, in a reorderable
playlist. {name} is the entry's words.emptyLabelstringDefault"No videos"What the playlist says while it has no entries. The empty slot replaces it.labelstringDefault"Playlist"The list's name, read by screen readers.movedLabelstringDefault"{name} moved to position {position} of {count}"What screen readers hear each time a key moves an entry, in a
reorderable playlist. {name} is the entry's words, {position} its
new place, counting from 1, and {count} the number of entries.noAdvancebooleanDefaultfalseStays on an entry when its clip ends, where the playlist would otherwise
play the next one. The player's controls, a press, and next() still
move. repeat="one" still plays the entry again.pickedUpLabelstringDefault"Picked up {name}"What screen readers hear when a pointer picks up an entry, in a
reorderable playlist. {name} is the entry's words.playingLabelstringDefault"Now playing {title}"What the live region says when the playlist moves to another entry.
{title} is the entry's name.reorderablebooleanDefaultfalseLets a reader move the entries, with Alt and the arrow keys or by
dragging one. The playlist moves no entry itself: you move your entries
on helix-reorder.repeat"all"|"one"What happens when an entry ends with no next one to go to. one plays the
same entry again, and all goes from the last entry back to the first.
Absent, the playlist stops on the last entry and sends helix-end.shufflebooleanDefaultfalseWhether the entries play in a random order. The order starts from the
entry that is current, and holds until shuffle is turned off or an entry
arrives or leaves, so previous goes back through what has played.
ReadTypeDescriptioncurrentEntryHelixHeadlessVideoPlaylistItemThe entry that is current, with the src, poster, value and name the
player was given, or undefined in an empty playlist.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The entries.emptyShown while the playlist has no entries. Defaults to empty-label.playerThe player that plays the entries.
EventTypeDescriptionhelix-activateHelixActivateEventThe current entry changed. The playlist already holds the new entry when this is sent, and detail.previous is the entry it left. currentEntry is the entry itself, with its src, poster and name.helix-before-activateHelixBeforeActivateEventThe current entry is about to change, and detail.cause says why: press, next, previous, ended, or removed. Cancelable: cancel it to keep the current entry.helix-before-reorderHelixBeforeReorderEventAn entry was moved to a new place, in a reorderable playlist, with every entry's value in the new order in detail.keys. Cancelable: cancel it to keep the entry where it is.helix-endHelixEndEventThe last entry finished playing, and the playlist stopped there. Not sent while repeat is set.helix-reorderHelixReorderEventFired after helix-before-reorder when nobody canceled it. Move your entries to the order in keys. Cancelable: cancel it to say the move did not happen.
MethodTypeDescriptionnext() => voidMoves to the next entry and plays it, as the player's next control does.
Follows shuffle, goes round under repeat="all", and stays on the last
entry otherwise.previous() => voidMoves to the previous entry and plays it, as the player's previous control
does. Under shuffle it goes back through the order that played.requestActive(next: string, cause: string) => booleanRequests a new current item, and returns whether the change was applied.
PartDescriptionemptyThe box that holds the empty slot, drawn while there are no entries.itemsThe list of entries.liveA live region that says which entry plays after the playlist moves. Visually hidden in the styled tier.playerThe region that holds the player.
Custom stateDescriptionendedThe last entry finished and the playlist stopped there, until an entry plays again.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Itemhelix-headless-video-playlist-itemOne entry in a video playlist.
PropTypeDescriptioncurrentbooleanDefaultfalseWhether this entry is the one playing.disabledbooleanDefaultfalsePrevents the entry from being chosen.focusablebooleanWhether the entry holds the playlist's tab stop. Unset, every entry is in
the tab order, which is what a server renders.posterstringDefault""The image shown before this entry plays, also used as the row's thumbnail.srcstringDefault""The file this entry plays.valuestringDefault""The entry's identifier, compared against the playlist's active.
ReadTypeDescriptiontextstringThe entry's name: its own text, without the content in its named slots.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The entry's name.indicatorA mark shown on the entry that is playing, such as an equalizer icon. Rendered only while the entry is current.mediaA thumbnail. Defaults to an image of poster.metaContent after the name, such as a duration or a date.
EventTypeDescriptionhelix-selectHelixSelectEventThe entry was chosen. Cancelable: cancel it to keep the current entry.
MethodTypeDescriptionfocus(options: FocusOptions) => voidFocuses the entry's button, which is where the playlist's arrow keys send
focus. The host itself takes no focus.
PartDescriptioncontainerThe list item that holds the button.indicatorThe indicator slot, at the end of the row, rendered only while the entry is playing. It draws no box until you give it one.itemThe row, which is a button.item-currentAdded to item for the entry that is playing.labelThe name and the content after it.mediaThe column at the start of the row.thumbnailThe image of poster, shown when the media slot is empty.
Custom stateDescriptioncurrentThe entry that is playing.draggingThe entry a pointer is dragging, in a reorderable playlist.drop-afterThe entry the dragged one would land after, which the drop indicator is drawn under.drop-beforeThe entry the dragged one would land before, which the drop indicator is drawn over.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Menuhelix-headless-video-playlist-menuThe playlist's entries, as a menu inside the player's control bar.
PropTypeDescriptionlabelstringDefault"Episodes"The name of the menu and its trigger, read by screen readers.placement"bottom"|"bottom-end"|"bottom-start"|"left"|"left-end"|"left-start"|"right"|"right-end"|"right-start"|"top"|"top-end"|"top-start"Default"top-end"Where the menu opens relative to its trigger.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescriptiontriggerReplaces the button that opens the menu.
EventTypeDescriptionhelix-selectHelixSelectEventAn entry was chosen. The event carries its value, and the playlist listens for it. Cancelable: cancel it to keep the current entry.
PartDescriptionentryOne entry in the menu.entry-endThe column at the end of an entry, which holds its shortcut. It is always present.entry-itemThe entry's row. It is an <a> when href is set.entry-markThe mark at the end of an entry: a check mark when it is checked, or a caret when it opens a submenu.entry-shortcutThe key drawn for an entry's shortcut. The playlist's entries set none.entry-shortcut-kbdThe key inside entry-shortcut.entry-shortcut-keyOne key of an entry's shortcut chord, inside entry-shortcut. The playlist's entries set none.entry-shortcut-separatorThe + between two keys of an entry's shortcut, where the platform writes one.entry-startThe column at the start of an entry. It is a slot and is always present.entry-surfaceThe panel an entry's submenu opens in beside it. The playlist's entries have none.menuThe menu that holds the entries.menu-backThe button that goes back from a submenu.menu-back-markThe icon on a submenu's back button.menu-emptyShown when there are no items to show.menu-headerThe bar above a submenu, holding the back button and the submenu's name.menu-liveThe inner menu's live part, the region screen readers announce its empty and loading messages from.menu-loadingShown while the items are loading.menu-search-fieldThe inner menu's filter field, drawn with filterable.menu-surfaceThe floating panel the menu is drawn on.menu-titleThe name of the submenu that is shown.posterAn entry's poster image, if it has one.triggerThe button that opens the menu.
Custom stateDescriptionsettledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionBeside The PlayerThe list next to the player.ControlledA playlist whose current clip your code sets, so a link can open a chosen clip.EventsThe events sent before and after the playlist changes the clip that plays.In The Control BarThe entries as a menu in the player's control bar, with no list next to the player.PlacementThe menu opening above its trigger, with one entry already playing.PreviewClips that play one after another in a single player.PreviewClips that play one after another in a single player.Repeat And ShuffleA playlist that plays its clips in a random order and starts again after the last one.