Lists and List Items
Quasar Lists and List Items 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. Items can also be used outside of a List.
Lists can encapsulate Items or Item-like components, for example QCollapsible or QSideLink (latter if setting item
property).
List Items have following content areas:
- left side and right side (usually equipped for supplemental actions represented by icons, avatars, images or letters, but not limited to only these)
- main content which usually is filled with a label (title) and sublabel (subtitle), form components, or anything else for that matter.
Basic Usage
We’ll cover each component on its own section later on, but for now, take a look to get a glimpse of how to structure your templates when using Lists.<q-list highlight>
<q-list-header>Recent chats</q-list-header>
<q-item>
<q-item-side avatar="/statics/boy-avatar.png" />
<q-item-main>
<q-item-tile label>John Doe</q-item-tile>
<q-item-tile sublabel>Quasar enthusiast</q-item-tile>
</q-item-main>
<q-item-side right>
<q-item-tile icon="chat_bubble" color="green" />
</q-item-side>
</q-item>
<q-item>
<q-item-side>
<q-item-tile avatar>
<img src="~assets/boy-avatar.png" />
</q-item-tile>
</q-item-side>
<q-item-main label="John Doe" sublabel="Quasar enthusiast" />
<q-item-side right icon="chat_bubble" />
</q-item>
<q-item-separator />
<q-list-header>Previous chats</q-list-header>
<q-item>
<q-item-side avatar="/statics/guy-avatar.png" />
<q-item-main label="Jack Doe" />
</q-item>
</q-list>
Notice that QItemMain and QItemSide can contain QItemTiles, or for convenience, you can use their own properties to define the content.
Due to how Webpack works in creating the bundle for your App, in some cases you may need to use QItemTile, like for avatars or images. The reason is simple: if you use QItemSide avatar
property, you must supply the path to the statics folder and cannot use the assets
folder or relative paths. Instead, the latter two can be used with a QItemTile wrapping an <img>
HTML tag. Look closely at image paths in the example above (/statics/guy-avata.png
vs ~assets/boy-avatar.png
). Also read about App Handling Static Assets to understand how Webpack includes assets into the bundle.
Components
Below is a list of Quasar components that you can use to define lists and list items:
- QList (encapsulating QItems and all other List related components)
- QListHeader (header of a section in QList)
- QItemSeparator (external Item separator/separator)
- QItem (encapsulating everything an Item contains)
- QItemSide (left or right side)
- QItemMain (for main content of an Item)
- QItemTile (for individual parts of QItemSide and QItemMain, like label, icon, avatar, image, …)
QList
QList encapsulates all other components mentioned. It’s not mandatory, but does help with maintaining a good design and can also define some properties that will be applied to all QItems (or QItem-like components) like multiline, separator, link, highlight and so on.
Vue Property | Type | Description |
---|---|---|
striped | Boolean | Apply highlight to QItems intermittently, starting with second QItem. |
striped-odd | Boolean | Apply highlight to QItems intermittently, starting with first QItem. |
highlight | Boolean | Apply highlight to all QItems. This works only on desktop when user hovers QItems. |
link | Boolean | Apply highlight and a pointer cursor to all QItems. |
dense | Boolean | Make QItems dense. |
sparse | Boolean | Make QItems sparse. |
multiline | Boolean | Make QItems multiline. |
separator | Boolean | Make QItems have a separator between them. |
inset-separator | Boolean | Make QItems have an inset separator between them. |
no-border | Boolean | Remove the default border around QList. |
QListHeader
Within QList, you can display a section header / title.
Vue Property | Type | Description |
---|---|---|
inset | Boolean | Place an inset separator. |
<q-list> |
QItemSeparator
If you want QItem external separators (there are internal ones too as you can see on QItem’s description later on this page), use the QItemSeparator component. It’s useful also to separate different sections of your QList, like for example, before a QListHeader.
Vue Property | Type | Description |
---|---|---|
inset | Boolean | Place an inset separator. |
<q-list> |
QItem
Vue Property | Type | Description |
---|---|---|
dense | Boolean | Make QItem dense (narrow paddings). |
sparse | Boolean | Make QItem sparse (large paddings). |
separator | Boolean | Make QItem have a separator between it and previous QItem. |
inset-separator | Boolean | Make QItem have an inset separator between it and previous QItem. |
multiline | Boolean | Make QItem multiline. Vertically aligns QItem sides to top. Useful for more than 2-3 lines QItem content. |
highlight | Boolean | Apply highlight to QItem. Works only on desktop when user hovers it. |
link | Boolean | Apply highlight and a pointer cursor to QItem. |
tag | String | Default HTML tag used is ‘div’, but this can be any HTML tag if you need to. Read below for more information. |
Also check the next section for more properties and to learn about how you can use your QItem as a Router Link.
Using QItem as a Router Link
If you want your QItem to act the same as Vue’s <router-link>
, then you can use these additional properties (which work exactly the same as <router-link>
):
Property | Type | Description |
---|---|---|
to | String / Object | Route to navigate to |
exact | Boolean | Match the exact route specified (and not also its children) when adding router-link-active CSS class. |
append | Boolean | Append route definition to current route when navigating. |
replace | Boolean | Replaces current route with the new one instead of adding it to the window history queue. |
For more details on these properties, please refer to the Vue Router documentation.
Render with specific HTML tag
Please refer to the example on how to use the tag
property shown below. In this example, we take advantage of the <label>
tag that browsers automatically connect to checkboxes (QCheckbox, QToggle) or radio inputs (QRadio). When a <label>
is clicked/tapped, then the wrapped checkboxes toggle their state (check / uncheck) and wrapped radios are being selected.<!--
We want a click/tap on the whole QItem
to toggle the checkbox, so we use tag="label"
to make QItem render with <label> tag.
-->
<q-item tag="label">
<q-item-side>
<q-checkbox v-model="checkboxModel" />
</q-item-side>
<q-item-main>
<q-item-tile label>Notifications</q-item-tile>
<q-item-tile sublabel>Notify me about updates to apps or games that I downloaded</q-item-tile>
</q-item-main>
</q-item>
QItemSide
Vue Property | Type | Description |
---|---|---|
color | String | Use a color from Quasar Color Palette. |
right | Boolean | Applies necessary design tweaks for right side of QItem. |
icon | String | Icon to use. Either use an icon, image, avatar or letter. |
image | String | URL to image to use (point to statics). Either use an icon, image, avatar or letter. |
avatar | String | URL to avatar to use (point to statics). Either use an icon, image, avatar or letter. |
letter | String | One character String to define a letter. Either use an icon, image, avatar or letter. |
stamp | String | For right side only. One character String to define a letter. Either use an icon, image, avatar or letter. |
tag | String | Default HTML tag that QItemTile gets rendered with is ‘div’, but this can be any HTML tag if you need to. |
Use the icon, image, avatar, letter or stamp properties or, for more control, insert QItemTiles instead. Use only one method or the other.
QItemMain
Vue Property | Type | Description |
---|---|---|
label | String | Label to use as title. |
sublabel | String | Label to use as subtitle. |
label-lines | String / Number | Number of lines the label can span to. |
sublabel-lines | String / Number | Number of lines the sublabel can span to. |
inset | Boolean | Useful when QItem has no left side, but you want to align your content as if it had a left side. |
tag | String | Default HTML tag that QItemTile gets rendered with is ‘div’, but this can be any HTML tag if you need to. |
Use the label properties or, for more control, insert QItemTiles to define the label and sublabel. Use only one method or the other.
QItemTile
QItemTile can be used for more control over the content of the left, right side or main content of QItem.
Vue Property | Type | Description |
---|---|---|
color | String | Use a color from Quasar Color Palette. |
icon | String | Icon to use. Either use an icon, image, avatar or letter as props. |
image | Boolean | Encapsulates an image. Its content must be an <img> with src attribute pointing to statics. Either use an icon, image, avatar or letter as props. |
avatar | Boolean | Encapsulates an avatar image. Its content must be an <img> with src attribute pointing to statics. Either use an icon, image, avatar or letter as props. |
letter | String | One character String to define a letter. Either use an icon, image, avatar or letter as props. |
tag | String | Default HTML tag that QItemTile gets rendered with is ‘div’, but this can be any HTML tag if you need to. |
There are more props available, but use only these within QItemMain:
Vue Property | Type | Description |
---|---|---|
label | String | Encapsulates the label / title of QItem. |
sublabel | String | Encapsulates the sub-label / sub-title of QItem. |
lines | String / Number | Number of lines the label/sublacel can span to. Ellipsis are used when overflowing. Use only in conjunction with label and sublabel . |
Using QCollapsible & QSideLink with QItems
QCollapsible and QSideLink are QItem wrappers, so you can use them with QItems within a QList. Here are two examples:<!--
Notice we use QCollapsibles and QItems
as direct children of QList.
We are basically building a menu.
-->
<q-list separator>
<!-- collapsible to hide sub-level menu entries -->
<q-collapsible icon="inbox" label="Inbox" label="Where your email is">
<q-item link to="/inbox/1">
<q-item-side icon="mail" />
<q-item-main label="Email 1" />
</q-item>
<q-item link to="/inbox/2">
<q-item-side icon="mail" />
<q-item-main label="Email 2" />
</q-item>
<q-collapsible icon="favorite" label="Favorites">
<q-item link to="/inbox/favorites/1">
<q-item-side icon="mail" />
<q-item-main :label="Favorite 1" />
</q-item>
<q-item to="/inbox/favorites/2">
<q-item-side icon="mail" />
<q-item-main :label="Favorite 2" />
</q-item>
</q-collapsible>
<q-item to="/inbox/3">
<q-item-side icon="mail" />
<q-item-main label="Email 3" />
</q-item>
</q-collapsible>
<!-- menu link -->
<q-item link to="/snoozed">
<q-item-side icon="schedule" />
<q-item-main>
<q-item-tile label>Snoozed</q-item-tile>
</q-item-main>
</q-item>
<!-- collapsible to hide sub-level menu entries -->
<q-collapsible icon="send" label="Sent">
<q-item to="/sent/1">
<q-item-side icon="mail" />
<q-item-main label="Email 1" />
</q-item>
</q-collapsible>
<!-- menu link -->
<q-item link to="/trash">
<q-item-side icon="delete" />
<q-item-main>
<q-item-tile label>Trash</q-item-tile>
</q-item-main>
</q-item>
</q-list>
Another complex example used on one of the sides of a QLayout, describing a menu with QItems, QCollapsible and QSideLinks:<q-list separator no-border>
<q-item>
<q-item-side avatar="/statics/boy-avatar.png" />
<q-item-main>
<q-item-tile label>John Doe</q-item-tile>
<q-item-tile sublabel>Administrator</q-item-tile>
</q-item-main>
</q-item>
<q-item-separator />
<q-list-header>Menu</q-list-header>
<q-side-link item icon="content_paste" to="/app" exact>
<q-item-main label="Dashboard" />
</q-side-link>
<q-side-link item icon="assignment" to="/app/registrations">
<q-item-main label="Registrations" />
</q-side-link>
<!--
Notice "indent" Boolean property on QCollapsible
which will make the sub-menu be indented.
Also, notice the "label" property which defines the
name of the menu item which opens up the sub-menu.
-->
<q-collapsible indent icon="event" label="Event" opened>
<q-side-link item to="/app/event">
<q-item-main label="Competitions" />
</q-side-link>
<q-collapsible menu label="Competitions" opened>
<div class="scroll" style="max-height: 400px">
<q-side-link
item
v-for="competition in competitions"
:key="competition"
:to="`/app/competitions/${competition.id}`"
exact
>
<q-item-main :label="competition.name" />
</q-side-link>
</div>
</q-collapsible>
<q-side-link item to="/app/other-info">
<q-item-main label="Other Information" />
</q-side-link>
</q-collapsible>
</q-list>
More Examples
Email list
<q-list highlight inset-separator style="max-width: 400px"> |
Right Side with Components
<q-list inset-separator> |
Chat List
<q-list highlight> |
One more example:<q-list>
<q-item>
<q-item-side icon="star" color="yellow" />
<q-item-main label="John Joe" />
<q-item-side right>
<q-item-tile avatar>
<img src="~assets/boy-avatar.png">
</q-item-tile>
</q-item-side>
</q-item>
<q-item-separator inset />
<q-item>
<q-item-side letter="D" />
<q-item-main label="John Joe" />
<q-item-side right avatar="/statics/boy-avatar.png" />
</q-item>
<q-item>
<q-item-side letter="J" />
<q-item-main label="Jim Jefferies" />
<q-item-side right avatar="/statics/linux-avatar.png" />
</q-item>
</q-list>
Folders and Files
<q-list> |
Settings
<q-list link> |
Embedding Form Components
<q-list link> |
Movies List
<q-list> |
Phonebook List
<q-list> |