HelixOverviewComponentsMapsGraphIntroductionInstallationDeriving a themeSandboxTheme builderVisual testingCortexDocsEngramBuildingTraceBuildingRecallDeclaredServicesInsightsGet in touchSource on GitHub
Loading the reference
ListView SourceEdit in SandboxView MarkdownCopy MarkdownOpen in ClaudeOpen in CursorA set of rows, announced as a list.StableSince 0.1.0DataUsageimport'@fusion.dev/helix/list'import'@fusion.dev/helix-headless/list'Preview
API ReferenceRoothelix-listA set of rows, announced as a list.
PropTypeDescriptioncanceledLabelstringDefault"Canceled"What screen readers hear when a held row is put back, or a move is
refused, in a reorderable list.disabledBehavior"all"|"selection"What disabled takes from a row, in a list that selects: all, which
passes over the row, or selection, which keeps the row out of the
selection and lets the keys reach it and Enter or a press act on it, as
React Aria's GridList takes disabledBehavior.dividedbooleanDefaultfalseDraws a line between rows.droppedLabelstringDefault"Dropped"What screen readers hear when a row is dropped, in a reorderable list.emptyLabelstringDefault""The text of the row shown while the list has no rows, where the empty
slot is empty. Empty, the default, shows no row.kind"default"|"description"|"ordered"|"unordered"The kind of list, which follows from the content.labelstringDefault""The list's name, read by screen readers.loadingbooleanDefaultfalseMarks the list as busy fetching more rows, and draws a row after the last
that says so. The list asks for no more while it is set.loadingLabelstringDefault"Loading more"The text of the row drawn while loading is set, where the loading slot is empty.loadMorebooleanDefaultfalseSends helix-load-more once the end of the list comes within a screen of
view, so you can add the next rows as a reader nears them.marker"rail"Where the marker sits.movedLabelstringDefault"{name} moved to position {position} of {count}"What screen readers hear each time an arrow key moves a held row, in a
reorderable list. {name} is the row's words, {position} the place it
would go, counting from 1, and {count} the number of rows.moveLabelstringDefault"Move {name}"The name of each row's grip, in a reorderable list. {name} is
replaced with the row's words.pickedUpLabelstringDefault"Picked up {name}"What screen readers hear when a key or a click picks up a row, in a
reorderable list. {name} is the row's words.reorderablebooleanDefaultfalseLets you move rows by dragging a grip, or with the keys. The list moves no
row itself: you move your data on helix-reorder.reversedbooleanDefaultfalseNumbers an ordered list downward, so the count falls row by row and ends at
its last row, as <ol reversed> does.selectionBehavior"replace"|"toggle"Default"toggle"What a press does to the rows already selected, in a list that selects:
toggle adds or takes out the row, and replace selects it alone and
lets the arrow keys carry the selection.selectionModeListSelectionModeMakes the list interactive: single selects one row, multiple any
number, and none moves and acts without selecting. Unset is a list a
reader reads, with no tab stop of its own.startnumberThe number of an ordered list's first row, as <ol start> is. Unset counts
from one, or down from the number of rows where reversed.type"1"|"a"|"A"|"i"|"I"The markers an ordered list draws. It takes the five values of <ol type>.valuestringDefault""The selected rows' values, separated by commas with no spaces, such as a,c, in a list that selects.
ReadTypeDescriptionrowsHelixHeadlessListItem[]The rows the list holds, in order.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The rows.emptyContent for the row shown while the list has no rows and none are loading. Falls back to empty-label.loadingContent for the row after the last while loading is set. Falls back to loading-label.
EventTypeDescriptionchangeEventFired once a press has changed which rows are selected.helix-actionHelixActionEventSent from a row when the reader acts on it: Enter, or a press in a list that selects nothing. Read the row from target. A row with href follows its link instead.helix-before-changeHelixBeforeChangeEventFired before a press changes which rows are selected, with the value it would leave. Cancelable.helix-before-reorderHelixBeforeReorderEventFired when a row is dropped at a new place, in a reorderable list, with every row's value in the new order. Cancelable: cancel it to keep the row where it is.helix-load-moreHelixLoadMoreEventFired, in a list with load-more, when the end of the list comes within a screen of view, once for each number of rows.helix-reorderHelixReorderEventFired after helix-before-reorder when nobody canceled it. Move your rows to the order in keys. Cancelable: cancel it to say the move did not happen.
PartDescriptiondrag-previewA copy of the row a pointer drags, which follows the pointer in the top layer until the row is let go, in a reorderable list. Hidden from assistive technology.emptyThe row shown while the list has no rows and none are loading, where empty-label or the empty slot gives it content. A grid row with one cell in a list that selects.liveThe region that says each step of a move to screen readers, in a reorderable list. Drawn from the first move. Visually hidden in the styled tier.loadingThe row after the last while loading is set. A grid row with one cell in a list that selects.
CSS PropertyDescription--list-drag-preview-background-colorThe fill behind the copy of a row a pointer drags.--list-drag-preview-border-colorThe color of the edge around the copy of a row a pointer drags.--list-drag-preview-border-widthThe width of the edge around the copy of a row a pointer drags. None by default, where the shadow lifts it.--list-drag-preview-opacityThe opacity of the copy of a row a pointer drags.--list-drag-preview-radiusThe corner radius of the copy of a row a pointer drags.--list-drag-preview-shadowThe shadow that raises the copy of a row a pointer drags over the page.--list-empty-colorThe color of the text in the row shown while the list has no rows.--list-empty-paddingThe space around the text in the row shown while the list has no rows.--list-firstThe number of the first row, written where start or reversed moves it.--list-gapThe space between rows.--list-loading-colorThe color of the text in the row drawn while loading is set.--list-loading-paddingThe space around the text in the row drawn while loading is set.--list-marker-gutterThe space that the markers of ordered and unordered lists sit in.--list-rail-inline-sizeThe width of the rail's track.--list-rail-styleThe counter style of the rail's numbers. Takes any list-style-type.--list-stepWhat each row adds to the number before it: 1, or -1 where reversed.
Custom stateDescriptionemptyWhile the list has no rows.loadingWhile loading is set.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Itemhelix-list-itemOne row of a list.
PropTypeDescriptioncurrent"date"|"location"|"page"|"step"|"time"|"true"Marks the row a reader is on: page for the page they are reading, step,
location, date or time for those, and written bare for the current
one of a set. It is aria-current on the row's link, or on the row where
it has none.disabledbooleanDefaultfalseTakes the row out of reach in a list with selection-mode: the arrow keys
pass over it and it cannot be selected or acted on. In a list with
disabled-behavior="selection", it cannot be selected and is reached and
acted on as any row is.focusablebooleanWhether the row holds its list's tab stop.gripstringThe name of the row's grip, written by a reorderable list from its
move-label, and unset in a list that does not reorder, which draws no
grip. No attribute: it is coordination between elements, as focusable
is.hrefstringDefault""The URL the row links to. Leave it empty for a row that is not a link.move"dragging"|"drop-after"|"drop-before"Where the row stands in a move, written by a reorderable list: the row
being moved, or the one the drop indicator is beside. Unset otherwise.relstringDefault""The link's rel value. You set it yourself. It is not derived from
target, for the reason Tree.Item gives.selectedbooleanWhether the row is selected, in a list that selects.selectionOnlybooleanDefaultfalseWhether disabled takes the row out of selection alone, written by a list
with disabled-behavior="selection". No attribute: it is coordination
between elements, as focusable is.targetstringDefault""Where the link opens. Use it for a row that leaves the site.valuestringDefault""What the row stands for in its list's value.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.wordsstringThe row's words, or none where the children are not known yet.
SlotDescription(default)The label.descriptionSecondary text under the label.endTrailing content.startLeading content, usually an icon or an avatar.
EventTypeDescriptionhelix-actionHelixActionEventThe reader pressed Enter on the row, or pressed the row in a list that selects nothing, in a list with selection-mode. Read the row from target. A row with href follows its link instead.
MethodTypeDescriptionfocusItem() => voidMoves focus to the row's cell, in a list with selection-mode.
PartDescriptiongripThe button that moves the row, in a reorderable list.grip-markThe icon on the grip.linkThe link, when the row has href. It holds every region except end.railThe cell that holds the number in a railed list.rowThe row's layout. It sits inside the host so the host can carry a list marker. In a list with selection-mode it is the grid cell that takes focus.row-currentAdded to row while the row is current.
CSS PropertyDescription--list-item-current-background-colorThe fill behind a row that is current.--list-item-disabled-opacityThe opacity of a disabled row.--list-item-dragging-opacityThe opacity of a row being moved, in a reorderable list.--list-item-drop-indicator-colorThe color of the line where a moved row would land.--list-item-drop-indicator-sizeThe thickness of the line where a moved row would land.--list-item-grip-colorThe color of the grip, in a reorderable list.--list-item-paddingThe padding inside the row.--list-item-rail-contentWhat the rail cell shows. The list sets it.--list-item-rail-displayWhether the row has a rail. The list sets it.--list-item-selected-background-colorThe fill behind a selected row, in a list that selects.--list-item-term-weightThe font weight of a term in a description list.
Custom stateDescriptiondraggingThe row is being moved, in a reorderable list.drop-afterThe row being moved goes after this one when it is dropped.drop-beforeThe row being moved goes before this one when it is dropped.focus-visibleThe row's cell has keyboard focus that the browser shows, in a list with selection-mode.selectedThe row is selected, in a list that selects.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Roothelix-headless-listA set of rows, announced as a list.
PropTypeDescriptioncanceledLabelstringDefault"Canceled"What screen readers hear when a held row is put back, or a move is
refused, in a reorderable list.disabledBehavior"all"|"selection"What disabled takes from a row, in a list that selects: all, which
passes over the row, or selection, which keeps the row out of the
selection and lets the keys reach it and Enter or a press act on it, as
React Aria's GridList takes disabledBehavior.droppedLabelstringDefault"Dropped"What screen readers hear when a row is dropped, in a reorderable list.emptyLabelstringDefault""The text of the row shown while the list has no rows, where the empty
slot is empty. Empty, the default, shows no row.kind"default"|"description"|"ordered"|"unordered"The kind of list, which follows from the content.labelstringDefault""The list's name, read by screen readers.loadingbooleanDefaultfalseMarks the list as busy fetching more rows, and draws a row after the last
that says so. The list asks for no more while it is set.loadingLabelstringDefault"Loading more"The text of the row drawn while loading is set, where the loading slot is empty.loadMorebooleanDefaultfalseSends helix-load-more once the end of the list comes within a screen of
view, so you can add the next rows as a reader nears them.movedLabelstringDefault"{name} moved to position {position} of {count}"What screen readers hear each time an arrow key moves a held row, in a
reorderable list. {name} is the row's words, {position} the place it
would go, counting from 1, and {count} the number of rows.moveLabelstringDefault"Move {name}"The name of each row's grip, in a reorderable list. {name} is
replaced with the row's words.pickedUpLabelstringDefault"Picked up {name}"What screen readers hear when a key or a click picks up a row, in a
reorderable list. {name} is the row's words.reorderablebooleanDefaultfalseLets you move rows by dragging a grip, or with the keys. The list moves no
row itself: you move your data on helix-reorder.reversedbooleanDefaultfalseNumbers an ordered list downward, so the count falls row by row and ends at
its last row, as <ol reversed> does.selectionBehavior"replace"|"toggle"Default"toggle"What a press does to the rows already selected, in a list that selects:
toggle adds or takes out the row, and replace selects it alone and
lets the arrow keys carry the selection.selectionModeListSelectionModeMakes the list interactive: single selects one row, multiple any
number, and none moves and acts without selecting. Unset is a list a
reader reads, with no tab stop of its own.startnumberThe number of an ordered list's first row, as <ol start> is. Unset counts
from one, or down from the number of rows where reversed.type"1"|"a"|"A"|"i"|"I"The markers an ordered list draws. It takes the five values of <ol type>.valuestringDefault""The selected rows' values, separated by commas with no spaces, such as a,c, in a list that selects.
ReadTypeDescriptionrowsHelixHeadlessListItem[]The rows the list holds, in order.whenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.
SlotDescription(default)The rows.emptyContent for the row shown while the list has no rows and none are loading. Falls back to empty-label.loadingContent for the row after the last while loading is set. Falls back to loading-label.
EventTypeDescriptionchangeEventFired once a press has changed which rows are selected.helix-actionHelixActionEventSent from a row when the reader acts on it: Enter, or a press in a list that selects nothing. Read the row from target. A row with href follows its link instead.helix-before-changeHelixBeforeChangeEventFired before a press changes which rows are selected, with the value it would leave. Cancelable.helix-before-reorderHelixBeforeReorderEventFired when a row is dropped at a new place, in a reorderable list, with every row's value in the new order. Cancelable: cancel it to keep the row where it is.helix-load-moreHelixLoadMoreEventFired, in a list with load-more, when the end of the list comes within a screen of view, once for each number of rows.helix-reorderHelixReorderEventFired after helix-before-reorder when nobody canceled it. Move your rows to the order in keys. Cancelable: cancel it to say the move did not happen.
PartDescriptiondrag-previewA copy of the row a pointer drags, which follows the pointer in the top layer until the row is let go, in a reorderable list. Hidden from assistive technology.emptyThe row shown while the list has no rows and none are loading, where empty-label or the empty slot gives it content. A grid row with one cell in a list that selects.liveThe region that says each step of a move to screen readers, in a reorderable list. Drawn from the first move. Visually hidden in the styled tier.loadingThe row after the last while loading is set. A grid row with one cell in a list that selects.
CSS PropertyDescription--list-firstThe number of the first row, written where start or reversed moves it.--list-stepWhat each row adds to the number before it: 1, or -1 where reversed.
Custom stateDescriptionemptyWhile the list has no rows.loadingWhile loading is set.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Itemhelix-headless-list-itemOne row of a list.
PropTypeDescriptioncurrent"date"|"location"|"page"|"step"|"time"|"true"Marks the row a reader is on: page for the page they are reading, step,
location, date or time for those, and written bare for the current
one of a set. It is aria-current on the row's link, or on the row where
it has none.disabledbooleanDefaultfalseTakes the row out of reach in a list with selection-mode: the arrow keys
pass over it and it cannot be selected or acted on. In a list with
disabled-behavior="selection", it cannot be selected and is reached and
acted on as any row is.focusablebooleanWhether the row holds its list's tab stop.gripstringThe name of the row's grip, written by a reorderable list from its
move-label, and unset in a list that does not reorder, which draws no
grip. No attribute: it is coordination between elements, as focusable
is.hrefstringDefault""The URL the row links to. Leave it empty for a row that is not a link.move"dragging"|"drop-after"|"drop-before"Where the row stands in a move, written by a reorderable list: the row
being moved, or the one the drop indicator is beside. Unset otherwise.relstringDefault""The link's rel value. You set it yourself. It is not derived from
target, for the reason Tree.Item gives.selectedbooleanWhether the row is selected, in a list that selects.selectionOnlybooleanDefaultfalseWhether disabled takes the row out of selection alone, written by a list
with disabled-behavior="selection". No attribute: it is coordination
between elements, as focusable is.targetstringDefault""Where the link opens. Use it for a row that leaves the site.valuestringDefault""What the row stands for in its list's value.
ReadTypeDescriptionwhenSettledPromise<void>Resolves a frame after the first update, when transitions are switched on.wordsstringThe row's words, or none where the children are not known yet.
SlotDescription(default)The label.descriptionSecondary text under the label.endTrailing content.startLeading content, usually an icon or an avatar.
EventTypeDescriptionhelix-actionHelixActionEventThe reader pressed Enter on the row, or pressed the row in a list that selects nothing, in a list with selection-mode. Read the row from target. A row with href follows its link instead.
MethodTypeDescriptionfocusItem() => voidMoves focus to the row's cell, in a list with selection-mode.
PartDescriptiongripThe button that moves the row, in a reorderable list.grip-markThe icon on the grip.linkThe link, when the row has href. It holds every region except end.rowThe row's layout. It sits inside the host so the host can carry a list marker. In a list with selection-mode it is the grid cell that takes focus.row-currentAdded to row while the row is current.
Custom stateDescriptiondraggingThe row is being moved, in a reorderable list.drop-afterThe row being moved goes after this one when it is dropped.drop-beforeThe row being moved goes before this one when it is dropped.focus-visibleThe row's cell has keyboard focus that the browser shows, in a list with selection-mode.selectedThe row is selected, in a list that selects.settledSet one frame after the first render. Transitions wait for it, so an element does not animate its own arrival.
Examples
NameDescriptionCountdownAn ordered list that counts down from five, as a ranking does.CurrentLinked rows with the page you are on marked as current.KindsAn ordered list, an unordered list, and a description list, one for each kind.LinkedRows that are links, where the whole row is clickable.PreviewRows with lines between them.PreviewRows with lines between them.RailedA numbered list, with the numbers in a rail to the side of the text.ReorderingRows you move by dragging a grip, or with the arrow keys after you press it.SelectableAn interactive list you move through with the arrow keys and select several rows from.