--- title: List and List Items related: - title: Expansion Item path: expansion-item.md - title: Slide Item path: slide-item.md - title: Separator path: separator.md --- The QList and QItem are a group of components which can work together to present multiple line items vertically as a single continuous element. They are best suited for displaying similar data types as rows of information, such as a contact list, a playlist or menu. Each row is called an Item. QItem can also be used outside of a QList too. Lists can encapsulate Items or Item-like components, for example [QExpansionItem](expansion-item.md) or [QSlideItem](slide-item.md). Also [QSeparator](separator.md) can be used to split up sections, where needed. List Items have the following pre-built child components: - **QItemSection** - An item section can have several uses for particular content. They are controlled via the `avatar`, `thumbnail` and `side` props. With no props, it will render the main section of your QItem (which spans to the fullest of available space). - **QItemLabel** - An item label is useful for predefined text content type within a QItemSection, or for header-like content of the QList itself. ## QList API ### Props - `bordered` (boolean, optional) Applies a default border to the component - `dense` (boolean, optional) Dense mode; occupies less space - `separator` (boolean, optional) Applies a separator between contained items - `dark` (boolean, optional), default `null` Notify the component that the background is a dark color - `padding` (boolean, optional) Applies a material design-like padding on top and bottom - `tag` (string, optional), default `'div'` HTML tag to use Examples: `'div'`, `'ul'`, `'ol'` - `role` (string, optional) *(added v2.25)* Overrides the default 'list' ARIA role; Contained QItems derive their own default role from it: with 'menu'/'menubar' the actionable items become 'menuitem's, while any other value stops the non-actionable items from claiming 'listitem' Examples: `'menu'`, `'listbox'`, `'none'` ### Slots - `#default` This is where the content goes; Suggestion: QItem, QExpansionItem, ... ## QItem API ### Props - `to` (string | object, optional) Equivalent to Vue Router 'to' property; Superseded by 'href' prop if used Examples: `'/home/dashboard'`, `{ name: 'my-route-name' }` - `exact` (boolean, optional) Equivalent to Vue Router 'exact' property; Superseded by 'href' prop if used - `replace` (boolean, optional) Equivalent to Vue Router 'replace' property; Superseded by 'href' prop if used - `active-class` (string, optional), default `'q-router-link--active'` Equivalent to Vue Router 'active-class' property; Superseded by 'href' prop if used Examples: `'my-active-class'` - `exact-active-class` (string, optional), default `'q-router-link--exact-active'` Equivalent to Vue Router 'active-class' property; Superseded by 'href' prop if used Examples: `'my-exact-active-class'` - `href` (string, optional) Native link href attribute; Has priority over the 'to'/'exact'/'replace'/'active-class'/'exact-active-class' props Examples: `'https://quasar.dev'` - `target` (string, optional) Native link target attribute; Use it only along with 'href' prop; Has priority over the 'to'/'exact'/'replace'/'active-class'/'exact-active-class' props Examples: `'_blank'`, `'_self'`, `'_parent'`, `'_top'` - `disable` (boolean, optional) Put component in disabled mode - `active` (boolean, optional), default `null` Put item into 'active' state - `dark` (boolean, optional), default `null` Notify the component that the background is a dark color - `clickable` (boolean, optional), default `null` Is QItem clickable? If it's the case, then it will add hover effects and emit 'click' events; when not set, the item is clickable if a 'click' listener is attached (a link or a 'label' tag always make it clickable) - `dense` (boolean, optional) Dense mode; occupies less space - `inset-level` (number, optional) Apply an inset; Useful when avatar/left side is missing but you want to align content with other items that do have a left side, or when you're building a menu Examples: `1` - `tabindex` (number | string, optional) Tabindex HTML attribute value Examples: `100`, `'0'` - `role` (string, optional) *(added v2.25)* Overrides the ARIA role that the item derives from its context: 'menuitem' when the wrapping QList has a 'menu'/'menubar' role (actionable items only), 'button' when clickable, 'listitem' when non-interactive inside a default QList, none otherwise Examples: `'menuitem'`, `'menuitemcheckbox'`, `'option'` - `tag` (string, optional), default `'div'` HTML tag to render; Suggestion: use 'label' when encapsulating a QCheckbox/QRadio/QToggle so that when user clicks/taps on the whole item it will trigger a model change for the mentioned components Examples: `'a'`, `'label'`, `'div'` - `manual-focus` (boolean, optional) Put item into a manual focus state; Enables 'focused' prop which will determine if item is focused or not, rather than relying on native hover/focus states - `focused` (boolean, optional) Determines focus state, ONLY if 'manual-focus' is enabled / set to true ### Events - `@click` Emitted when the component is clicked Params: - `evt` (Event, optional) JS event object; If you are using route navigation ('to'/'replace' props) and you want to cancel navigation then call evt.preventDefault() synchronously in your event handler - `go` (Function, optional) Available ONLY if you are using route navigation ('to'/'replace' props); When you need to control the time at which the component should trigger the route navigation then call evt.preventDefault() synchronously and then call this function at your convenience; Useful if you have async work to be done before the actual route navigation or if you want to redirect somewhere else Function signature: `(opts?: object) => Promise` Params: - `opts` (object, optional) Optional options Object shape: - `to` (string | object, optional) Equivalent to Vue Router 'to' property; Specify it explicitly otherwise it will be set with same value as component's 'to' prop Examples: `'/home/dashboard'`, `{ name: 'my-route-name' }` - `replace` (boolean, optional) Equivalent to Vue Router 'replace' property; Specify it explicitly otherwise it will be set with same value as component's 'replace' prop - `returnRouterError` (boolean, optional) Return the router error, if any; Otherwise the returned Promise will always fulfill Returns: `Promise` Returns the router's navigation promise ### Slots - `#default` This is where QItem's content goes ## QItemSection API ### Props - `avatar` (boolean, optional) Render an avatar item side (does not needs 'side' prop to be set) - `thumbnail` (boolean, optional) Render a thumbnail item side (does not needs 'side' prop to be set) - `side` (boolean, optional) Renders as a side of the item - `top` (boolean, optional) Align content to top (useful for multi-line items) - `no-wrap` (boolean, optional) Do not wrap text (useful for item's main content) ### Slots - `#default` Section's actual content ## QItemLabel API ### Props - `overline` (boolean, optional) Renders an overline label - `caption` (boolean, optional) Renders a caption label - `header` (boolean, optional) Renders a header label - `lines` (number | string, optional) Apply ellipsis when there's not enough space to render on the specified number of lines; ### Slots - `#default` The content of the label; Suggestion: text ## Usage ### Basic ```vue ``` > [!NOTE] > A QItem with a `@click` listener is clickable by default (v2.29+): it gets the hover effects, keyboard activation and its `click` event without the `clickable` prop. Set `clickable` explicitly only when there is no listener (a `v-close-popup` entry, for example) or when you need to toggle the behavior through a boolean; an explicit `clickable="false"` wins over the listener. Example "Force dark mode": ```vue ``` Example "Dense": ```vue ``` ### QItemSection Example "Left avatar/thumbnail QItemSection": ```vue ``` Example "Right avatar/thumbnail QItemSection": ```vue ``` > [!TIP] > When you have multi-line items, you could use `top` property on QItemSection side/avatar to align the sections to top, overriding default middle alignment. Example "Side QItemSection": ```vue ``` ### Active state Example "Active prop": ```vue ``` ### QItemLabel > [!WARNING] > Notice you can handle label overflow with `lines` prop, telling it how many lines it can span. However, this feature uses Webkit specific CSS so won't work in IE/Edge. Example "ItemLabel": ```vue ``` ### More involved examples Example "Contact list": ```vue ``` Example "Settings": ```vue ``` Example "Emails": ```vue ``` Example "Folder listing": ```vue ``` For demoing purposes in the example below, we're using the `active` prop instead of QItem's router props (`to`, `exact`). UMD doesn't have Vue Router so you wouldn't be able to play with it in Codepen/jsFiddle. Example "Menu": ```vue ``` > [!TIP] > For more complex menus, consider also using [QExpansionItem](expansion-item.md). ### Connecting to Vue Router You can use QItems together with Vue Router through `` properties bound to it. These allow for listening to the current app route and also triggering a route when clicked/tapped. ```html

Inbox

``` You can also delay, cancel or redirect navigation, as seen below. For a more in-depth description of the `@click` event being used below, please refer to QItem API card at the top of the page. Example "Links with delayed, cancelled or redirected navigation": ```vue ``` ## Accessibility *(v2.25+)* QList exposes itself with the [WAI-ARIA `list` role](https://www.w3.org/TR/wai-aria-1.2/#list) by default (implicitly so when rendered as `ul`/`ol` through the `tag` prop) and the `role` prop overrides that. Each QItem derives its default role from the QList wrapping it: | QItem | inside default QList | inside QList with `role="menu"`/`"menubar"` | outside QList / other QList `role` | | --- | --- | --- | --- | | with `clickable`, a `@click` listener or a link | `button` / native link | `menuitem` | `button` / native link | | non-interactive | `listitem` | none | none | This keeps the produced markup valid: ARIA's `list` may only own `listitem` children (which in turn require a list parent, so a standalone QItem claims no role), while `menu`/`menubar` may only own `menuitem`-type entries — declaring the role once on the QList is enough, as in the "Basic" example of [QMenu's Accessibility section](menu.md#accessibility). The `role` prop on QItem overrides the derived role for a single item (e.g. `menuitemcheckbox`/`menuitemradio` for toggle entries — managing `aria-checked` is then up to you). > [!WARNING] > A list made up of only interactive items has no valid claim to the `list` role — such a container owns no `listitem` children. Declare what it actually is: `role="menu"` if it pops up as a list of commands, or `role="none"` to keep the items (announced as buttons/links) without list semantics.