VList API

Props

name	type	default
`activatable`	boolean	false
Designates whether the list items are activatable. Additionally, sets necessary accessibility attributes internally.
`activated`	unknown	undefined
Array of ids of activated nodes.
`active-class`	string	undefined
The class applied to the component when it is in an active state.
`active-color`	string	undefined
Deprecated, use `color` instead.
`active-strategy`	\| 'single-leaf' \| 'leaf' \| 'independent' \| 'single-independent' \| ActiveStrategy \| ((mandatory: boolean) => ActiveStrategy)	undefined
Affects how items with children behave when activated. If not specified, the single-independent strategy will be used. leaf: Only leaf nodes (items without children) can be activated. single-leaf: Similar as leaf, but only a single item can be activated at a time. independent: All nodes can be activated whether they have children or not. single-independent: Similar as independent, but only a single item can be activated at a time.
`base-color`	string	undefined
Sets the color of component when not focused.
`bg-color`	string	undefined
Applies specified color to the control’s background. Used on components that also support the color prop. - supports utility colors with or without `bg-` prefix (for example `success`, `purple` or `bg-purple`) or CSS color (`#033` or `rgba(255, 0, 0, 0.5)`). Find a list of built-in classes on the colors page.
`border`	string \| number \| boolean	false
Applies utility border classes to the component. To use it, you need to omit the `border-` prefix, (for example use `border-sm` as `border="sm"`). Find a list of the built-in border classes on the borders page.
`collapse-icon`	\| string \| (new () => any) \| FunctionalComponent \| (string \| [string, number])[]	undefined
Icon to display when the list item is expanded.
`color`	string	undefined
Applies specified color to the control - supports utility colors with or without `text-` prefix (for example `success`, `purple` or `text-purple`) or CSS color (`#033` or `rgba(255, 0, 0, 0.5)`). Find a list of built-in classes on the colors page.
`density`	'default' \| 'comfortable' \| 'compact'	'default'
Adjusts the vertical height used by the component.
`disabled`	boolean	false
Puts all children inputs into a disabled state.
`elevation`	string \| number	undefined
Designates an elevation applied to the component between 0 and 5. You can find more information on the elevation page.
`expand-icon`	\| string \| (new () => any) \| FunctionalComponent \| (string \| [string, number])[]	undefined
Icon to display when the list item is collapsed.
`filterable`	boolean	false
FOR INTERNAL USE ONLY Prevents list item selection using [space] key and pass it back to the text input. Used internally for VAutocomplete and VCombobox.
`height`	string \| number	undefined
Sets the height for the component.
`indent` New in v3.11.0	string \| number	undefined
Overrides the indent size for nested groups.
`item-children`	SelectItemKey	'children'
Property on supplied `items` that contains its children.
`item-props`	SelectItemKey	'props'
Props object that will be applied to each item component. `true` will treat the original object as raw props and pass it directly to the component.
`items`	any[]	[]
Can be an array of objects or strings. By default objects should have a title property, and can optionally have a props property containing any VListItem props, a value property to allow selection, and a children property containing more item objects. Keys to use for these can be changed with the item-title, item-value, item-props, and item-children props.
`items-registration` New in v3.11.0	'props' \| 'render'	'render'
When set to ‘props’, skips rendering collapsed items/nodes (for significant performance gains).
`item-title`	SelectItemKey	'title'
Property on supplied `items` that contains its title.
`item-type`	SelectItemKey	'type'
Designates the key on the supplied items that is used for determining the nodes type.
`item-value`	SelectItemKey	'value'
Property on supplied `items` that contains its value.
`lines`	false \| 'one' \| 'two' \| 'three'	'one'
Designates a minimum-height for all children `v-list-item` components. This prop uses line-clamp and is not supported in all browsers.
`mandatory`	boolean	false
Forces at least one item to always be selected (if available).
`max-height`	string \| number	undefined
Sets the maximum height for the component.
`max-width`	string \| number	undefined
Sets the maximum width for the component.
`min-height`	string \| number	undefined
Sets the minimum height for the component.
`min-width`	string \| number	undefined
Sets the minimum width for the component.
`nav`	boolean	false
An alternative styling that reduces `v-list-item` width and rounds the corners. Typically used with v-navigation-drawer.
`navigation-index`	number	undefined
Specifies the currently selected navigation index when using `navigationStrategy="track"`. Can be used with `v-model:navigationIndex` for two-way binding. Items at this index receive visual keyboard focus styling and automatic scrolling. Note: Only works with the `items` prop, not with slotted items.
`navigation-strategy`	'focus' \| 'track'	'focus'
Determines keyboard navigation behavior. focus (default) moves DOM focus to items, suitable for traditional lists. track provides visual keyboard focus without moving DOM focus, ideal for command palettes and autocomplete where an external element retains focus. When track mode is active, items automatically receive `tabindex="-1"`, proper `aria-activedescendant` is set on the list container, and keyboard-focused items display focus-visible styling with auto-scrolling.
`opened`	unknown	undefined
An array containing the values of currently opened groups. Can be two-way bound with `v-model:opened`.
`open-strategy`	'list' \| 'multiple' \| 'single' \| OpenStrategy	'list'
Affects how items with children behave when expanded. multiple: Any number of groups can be open at once. single: Only one group at each level can be open, opening a group will cause others to close. list: Multiple, but all other groups will close when an item is selected.
`prepend-gap` New in v3.11.0	string \| number	undefined
Sets the horizontal spacing between prepend slot and the main content within list item. Also affects indent to ensure expected alignment of group children.
`return-object`	boolean	false
Changes the selection behavior to return the object directly rather than the value specified with item-value.
`rounded`	string \| number \| boolean	undefined
Designates the border-radius applied to the component. This can be 0, xs, sm, true, lg, xl, pill, circle, and shaped. Find more information on available border radius classes on the Border Radius page.
`selectable`	boolean	false
Designates whether the list items are selectable. Additionally, sets necessary accessibility attributes internally.
`selected`	unknown	undefined
An array containing the values of currently selected items. Can be two-way bound with `v-model:selected`.
`select-strategy`	\| 'single-leaf' \| 'leaf' \| 'independent' \| 'single-independent' \| 'classic' \| 'trunk' \| 'branch' \| SelectStrategy \| ((mandatory: boolean) => SelectStrategy)	'single-leaf'
Affects how items with children behave when selected. leaf: Only leaf nodes (items without children) can be selected. independent: All nodes can be selected whether they have children or not. classic: Selecting a parent node will cause all children to be selected, parent nodes will be displayed as selected if all their descendants are selected. Only leaf nodes will be added to the model. trunk: Same as classic but if all of a node’s children are selected then only that node will be added to the model. branch: Same as classic but if any of a node’s children are selected then that node will also be added to the model.
`slim`	boolean	false
Reduces horizontal spacing for badges, icons, tooltips, and avatars within slim list items to create a more compact visual representation.
`tag`	string \| (new () => any) \| FunctionalComponent	'div'
Specify a custom tag used on the root element.
`theme`	string	undefined
Specify a theme for this component and all of its children.
`tile`	boolean	false
Removes any applied border-radius from the component.
`value-comparator`	(a: any, b: any) => boolean	undefined
Apply a custom comparison algorithm to compare model-value and values contains in the items prop.
`variant`	'flat' \| 'text' \| 'elevated' \| 'tonal' \| 'outlined' \| 'plain'	'text'
Applies a distinct style to the component.
`width`	string \| number	undefined
Sets the width for the component.

Events

name	type
`click:activate`	[{ id: unknown; value: boolean; path: unknown[] }]
Emitted when the list item is activated.
`click:open`	[{ id: unknown; value: boolean; path: unknown[] }]
Emitted when the list item is opened.
`click:select`	[{ id: unknown; value: boolean; path: unknown[] }]
Emitted when the list item is selected.
`update:activated`	[unknown]
Emitted when the list item is activated.
`update:navigationIndex`	[number]
Emitted when keyboard navigation occurs in `navigationStrategy="track"`. The event payload is the new index of the selected item. Automatically skips non-selectable items like dividers and subheaders.
`update:opened`	[unknown]
Emitted when the list item is opened.
`update:selected`	[unknown]
Emitted when the list item is selected.

Slots

{
  index: number
  depth: number
  path: number[]
  isFirst: boolean
  isLast: boolean
  isActive: boolean
  isOpen: boolean
  isSelected: boolean
  isIndeterminate: boolean
  isDisabled: boolean
  select: (value: boolean) => void
} & { item: any }

never

{ props: { title: string; value: any; [string]: any } }

{ props: { title: string; value: any; [string]: any } }

{
  props: { title: string; value: any; [string]: any } & { index: number }
}

{
  index: number
  depth: number
  path: number[]
  isFirst: boolean
  isLast: boolean
  isActive: boolean
  isOpen: boolean
  isSelected: boolean
  isIndeterminate: boolean
  isDisabled: boolean
  select: (value: boolean) => void
} & { item: any }

{ props: { title: string; value: any; [string]: any } }

{ subtitle: string | number | boolean } & { item: any }

{ title: string | number | boolean } & { item: any }

`append`
Adds an item inside the input and after input content.
`default`
The default Vue slot.
`divider`
Slot for rendering custom dividers. Receives `{ props }` containing divider item data including `value`. Note: dividers do not receive `index` since they are not navigable items.
`header`
Slot for rendering custom group headers when using nested items. Receives `{ props }` containing the group’s header item data plus activator props for expand/collapse functionality.
`item`
Slot for rendering custom list items. Receives `{ props }` where `props` contains item data (`title`, `subtitle`, `value`, etc.) plus `index` (the item’s position in the list). Use this to completely customize item rendering while still using VList’s navigation and selection features.
`prepend`
Adds an item outside the input and before input content.
`subheader`
Slot for rendering custom subheaders. Receives `{ props }` containing subheader item data including `title` and `value`. Note: subheaders do not receive `index` since they are not navigable items.
`subtitle`
Slot for the component’s subtitle content.
`title`
Slot for the component’s title content.

Exposed

Map<unknown, unknown[]>

(
  location: number | 'next' | 'prev' | 'first' | 'last',
  options: FocusOptions,
) => void

(id: unknown) => unknown[]

number

(id: unknown, value: boolean, event: Event) => void

Map<unknown, unknown>

(id: unknown, value: boolean, event: Event) => void

`children`
The nested list items within the component.
`focus`
Focus the list item.
`getPath`
Get the position of an item within the nested structure.
`navigationIndex`
A computed ref that returns the current navigation index when using `navigationStrategy="track"`. Returns -1 when no item is selected or when using `navigationStrategy="focus"`.
`open`
Open the list item.
`parents`
The parent list items within the component.
`select`
The function used to select an items. The first argument expects the value of the item.

SASS Variables

name	default
`$list-background`	rgba(var(--v-theme-surface))
`$list-border`	( $list-border-color, $list-border-style, $list-border-width, $list-border-thin-width )
`$list-border-color`	settings.$border-color-root
`$list-border-radius`	0
`$list-border-style`	settings.$border-style-root
`$list-border-thin-width`	thin
`$list-border-width`	0
`$list-color`	tools.theme-color('on-surface', var(--v-high-emphasis-opacity))
`$list-density`	('default': 0, 'comfortable': -1, 'compact': -2)
`$list-disabled-opacity`	0.6
`$list-elevation`	0
`$list-indent-size`	16px
`$list-item-action-margin-end`	8px
`$list-item-action-margin-start`	8px
`$list-item-action-spacer-width`	16px
`$list-item-avatar-margin-end`	16px
`$list-item-avatar-margin-start`	16px
`$list-item-border`	( $list-item-border-color, $list-item-border-style, $list-item-border-width, $list-item-border-thin-width )
`$list-item-border-color`	settings.$border-color-root
`$list-item-border-radius`	0
`$list-item-border-style`	settings.$border-style-root
`$list-item-border-thin-width`	thin
`$list-item-border-width`	0
`$list-item-content-min-width`	40px
`$list-item-elevation`	1
`$list-item-icon-active-opacity`	1
`$list-item-icon-margin-end`	32px
`$list-item-icon-margin-start`	32px
`$list-item-icon-opacity`	var(--v-medium-emphasis-opacity)
`$list-item-media-margin-bottom`	0
`$list-item-media-margin-end`	16px
`$list-item-media-margin-start`	16px
`$list-item-media-margin-top`	0
`$list-item-media-three-line-margin-bottom`	0
`$list-item-media-three-line-margin-top`	0
`$list-item-media-two-line-margin-bottom`	-4px
`$list-item-media-two-line-margin-top`	-4px
`$list-item-min-height`	40px
`$list-item-nav-margin-top`	4px
`$list-item-nav-subtitle-font-size`	.75rem
`$list-item-nav-subtitle-font-weight`	tools.map-deep-get(settings.$typography, 'body-medium', 'weight')
`$list-item-nav-subtitle-letter-spacing`	tools.map-deep-get(settings.$typography, 'body-medium', 'letter-spacing')
`$list-item-nav-subtitle-line-height`	1rem
`$list-item-nav-subtitle-typography`	( $list-item-nav-subtitle-font-size, $list-item-nav-subtitle-font-weight, $list-item-nav-subtitle-letter-spacing, $list-item-nav-subtitle-line-height, null )
`$list-item-nav-title-font-size`	.8125rem
`$list-item-nav-title-font-weight`	500
`$list-item-nav-title-letter-spacing`	normal
`$list-item-nav-title-line-height`	1rem
`$list-item-nav-title-typography`	( $list-item-nav-title-font-size, $list-item-nav-title-font-weight, $list-item-nav-title-letter-spacing, $list-item-nav-title-line-height, null )
`$list-item-one-line-min-height`	48px
`$list-item-padding`	4px 16px
`$list-item-plain-opacity`	.62
`$list-item-prepend-size`	40px
`$list-item-rounded-border-radius`	map.get(settings.$rounded, null)
`$list-item-slim-action-spacer-width`	4px
`$list-item-slim-avatar-spacer-width`	4px
`$list-item-slim-prepend-size`	28px
`$list-item-slim-spacer-width`	20px
`$list-item-subtitle-font-size`	tools.map-deep-get(settings.$typography, 'body-medium', 'size')
`$list-item-subtitle-font-weight`	tools.map-deep-get(settings.$typography, 'body-medium', 'weight')
`$list-item-subtitle-letter-spacing`	tools.map-deep-get(settings.$typography, 'body-medium', 'letter-spacing')
`$list-item-subtitle-line-height`	1rem
`$list-item-subtitle-opacity`	var(--v-list-item-subtitle-opacity, var(--v-medium-emphasis-opacity))
`$list-item-subtitle-overflow-wrap`	break-word
`$list-item-subtitle-padding`	0
`$list-item-subtitle-text-transform`	none
`$list-item-subtitle-typography`	( $list-item-subtitle-font-size, $list-item-subtitle-font-weight, $list-item-subtitle-letter-spacing, $list-item-subtitle-line-height, $list-item-subtitle-text-transform )
`$list-item-subtitle-word-break`	initial
`$list-item-three-line-min-height`	88px
`$list-item-three-line-padding`	16px 16px
`$list-item-title-font-size`	tools.map-deep-get(settings.$typography, 'body-large', 'size')
`$list-item-title-font-weight`	tools.map-deep-get(settings.$typography, 'body-large', 'weight')
`$list-item-title-hyphens`	auto
`$list-item-title-letter-spacing`	tools.map-deep-get(settings.$typography, 'body-large', 'letter-spacing')
`$list-item-title-line-height`	tools.map-deep-get(settings.$typography, 'body-large', 'line-height')
`$list-item-title-overflow-wrap`	normal
`$list-item-title-padding`	0
`$list-item-title-text-transform`	none
`$list-item-title-typography`	( $list-item-title-font-size, $list-item-title-font-weight, $list-item-title-letter-spacing, $list-item-title-line-height, $list-item-title-text-transform )
`$list-item-title-word-break`	normal
`$list-item-title-word-wrap`	break-word
`$list-item-two-line-min-height`	64px
`$list-item-two-line-padding`	12px 16px
`$list-item-variants`	( $list-background, $list-color, $list-item-elevation, $list-item-plain-opacity, 'v-list-item' )
`$list-nav-padding`	8px
`$list-nav-subheader-font-size`	.75rem
`$list-padding`	8px 0
`$list-rounded-border-radius`	map.get(settings.$rounded, null)
`$list-subheader-color`	tools.theme-color('on-surface', var(--v-medium-emphasis-opacity))
`$list-subheader-font-size`	.875rem
`$list-subheader-font-weight`	400
`$list-subheader-inset-padding-start`	56px
`$list-subheader-line-height`	1.375rem
`$list-subheader-min-height`	40px
`$list-subheader-min-height-multiplier`	1
`$list-subheader-padding-end`	16px
`$list-subheader-padding-top`	0
`$list-subheader-transition`	0.2s min-height settings.$standard-easing
`$list-theme`	( $list-background, $list-color )

#VList API

VList API