List

A List is a vertical arrangement of items that can contain text or images.

Usage

Import the component:

import 'mdui/components/list.js';
import 'mdui/components/list-item.js';
import 'mdui/components/list-subheader.js';

Import the TypeScript type:

import type { List } from 'mdui/components/list.js';
import type { ListItem } from 'mdui/components/list-item.js';
import type { ListSubheader } from 'mdui/components/list-subheader.js';

Example:

Subheader

Item 1

Item 2

<mdui-list>
  <mdui-list-subheader>Subheader</mdui-list-subheader>
  <mdui-list-item>Item 1</mdui-list-item>
  <mdui-list-item>Item 2</mdui-list-item>
</mdui-list>

Examples

Text Content

The headline attribute on <mdui-list-item> sets the primary text, while the description attribute sets the secondary text.

<mdui-list>
  <mdui-list-item headline="Headline"></mdui-list-item>
  <mdui-list-item headline="Headline" description="Supporting text"></mdui-list-item>
</mdui-list>

Code

Alternatively, use the default slot for the primary text and the description slot for the secondary text.

Headline

Headline Supporting text

<mdui-list>
  <mdui-list-item>Headline</mdui-list-item>
  <mdui-list-item>
    Headline
    <span slot="description">Supporting text</span>
  </mdui-list-item>
</mdui-list>

Code

By default, both primary and secondary text are displayed in full. To limit the number of lines, use the headline-line and description-line attributes. The maximum limit is 3 lines.

Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text

<mdui-list>
  <mdui-list-item headline-line="1" description-line="2">
    Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline Headline
    <span slot="description">Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text Supporting text</span>
  </mdui-list-item>
</mdui-list>

Code

Side Content

The icon and end-icon attributes on <mdui-list-item> add Material Icons to the left and right sides, respectively.

Headline

<mdui-list>
  <mdui-list-item icon="people" end-icon="arrow_right">Headline</mdui-list-item>
</mdui-list>

Code

Alternatively, use the icon and end-icon slots to add elements to the left and right sides of the list item.

Headline

<mdui-list>
  <mdui-list-item>
    Headline
    <mdui-avatar slot="icon" src="https://avatars.githubusercontent.com/u/3030330?s=40&v=4"></mdui-avatar>
    <mdui-checkbox slot="end-icon"></mdui-checkbox>
  </mdui-list-item>
</mdui-list>

Code

Link

The href attribute turns the list into a link, with download, target, and rel attributes available for link-related functionality.

Headline

<mdui-list>
  <mdui-list-item href="https://www.mdui.org" target="_blank">Headline</mdui-list-item>
</mdui-list>

Code

Disabled State

The disabled attribute on <mdui-list-item> disables the item. This also disables components within the list item.

Headline

<mdui-list>
  <mdui-list-item disabled>Headline</mdui-list-item>
  <mdui-list-item>Headline</mdui-list-item>
</mdui-list>

Code

Active State

The active attribute on <mdui-list-item> activates the item.

Headline

<mdui-list>
  <mdui-list-item active>Headline</mdui-list-item>
  <mdui-list-item>Headline</mdui-list-item>
</mdui-list>

Code

Nonclickable State

The nonclickable attribute on <mdui-list-item> removes mouse hover and click ripple effects.

Headline

<mdui-list>
  <mdui-list-item nonclickable>Headline</mdui-list-item>
  <mdui-list-item>Headline</mdui-list-item>
</mdui-list>

Code

Rounded Shape

The rounded attribute on <mdui-list-item> gives the item a rounded appearance.

Headline

<mdui-list>
  <mdui-list-item rounded>Headline</mdui-list-item>
  <mdui-list-item rounded>Headline</mdui-list-item>
</mdui-list>

Code

Vertical Alignment

The alignment attribute on <mdui-list-item> aligns elements on the left and right. Possible values:

start: top alignment.
center: center alignment.
end: bottom alignment.

Headline

<mdui-list>
  <mdui-list-item alignment="start" description="Supporting text">
    Headline
    <mdui-icon slot="icon" name="people"></mdui-icon>
  </mdui-list-item>
  <mdui-list-item alignment="center" description="Supporting text">
    Headline
    <mdui-icon slot="icon" name="people"></mdui-icon>
  </mdui-list-item>
  <mdui-list-item alignment="end" description="Supporting text">
    Headline
    <mdui-icon slot="icon" name="people"></mdui-icon>
  </mdui-list-item>
</mdui-list>

Code

Custom Content

The custom slot in <mdui-list-item> allows for full customization of the list item content.

test

<mdui-list>
  <mdui-list-item>
    <div slot="custom" style="display: flex;">
      <mdui-icon name="people"></mdui-icon>
      <div>test</div>
    </div>
  </mdui-list-item>
</mdui-list>

Code

`mdui-list-item` API

Properties

Attribute	Property	Type	Default
`headline`	`headline`	`string`	-
Main text. Alternatively, use the default slot.
`headline-line`	`headlineLine`	`1 \| 2 \| 3`	-
Line limit for main text. Truncates after exceeding. Default is no limit. Possible values: `1`: Single-line text, truncates after exceeding `2`: Double-line text, truncates after exceeding. `3`: Triple-line text, truncates after exceeding.
`description`	`description`	`string`	-
Subtext. Alternatively, use `slot="description"`.
`description-line`	`descriptionLine`	`1 \| 2 \| 3`	-
Line limit for subtext. Truncates after exceeding. Default is no limit. Possible values: `1`: Single-line text, truncates after exceeding `2`: Double-line text, truncates after exceeding. `3`: Triple-line text, truncates after exceeding.
`icon`	`icon`	`string`	-
Material Icons name on the left. Alternatively, use `slot="icon"`.
`end-icon`	`endIcon`	`string`	-
Material Icons name on the right. Alternatively, use `slot="end-icon"`.
`disabled`	`disabled`	`boolean`	`false`
Disables the list item. Grays out the item and disables elements like `<mdui-checkbox>`, `<mdui-radio>`, `<mdui-switch>`.
`active`	`active`	`boolean`	`false`
Activates the list item.
`nonclickable`	`nonclickable`	`boolean`	`false`
Makes the list item non-clickable. Elements like `<mdui-checkbox>`, `<mdui-radio>`, `<mdui-switch>` remain interactive.
`rounded`	`rounded`	`boolean`	`false`
Applies rounded style to the list item.
`alignment`	`alignment`	`'start' \| 'center' \| 'end'`	`'center'`
Vertical alignment of the list item. Possible values: `start`: Top alignment. `center`: Center alignment. `end`: Bottom alignment.
`href`	`href`	`string`	-
The URL for the hyperlink. If specified, the component renders as an `<a>` element and can use link-related attributes.
`download`	`download`	`string`	-
Instructs the browser to treat the linked URL as a download. Note: This is only available when `href` is specified.
`target`	`target`	`'_blank' \| '_parent' \| '_self' \| '_top'`	-
Defines where to display the linked URL. Possible values: `_blank`: Opens in a new tab or window. `_parent`: Opens in the parent browsing context or `_self` if no parent exists. `_self`: Opens in the current browsing context. (Default). `_top`: Opens in the topmost browsing context or `_self` if no ancestors exist. Note: This is only available when `href` is specified.
`rel`	`rel`	`'alternate' \| 'author' \| 'bookmark' \| 'external' \| 'help' \| 'license' \| 'me' \| 'next' \| 'nofollow' \| 'noreferrer' \| 'opener' \| 'prev' \| 'search' \| 'tag'`	-
Specifies the relationship of the linked URL as space-separated link types. Possible values: `alternate`: Alternate versions of the current document. `author`: Author of the current document or article. `bookmark`: Permanent link for the nearest ancestor section. `external`: The referenced document is not part of the same site as the current document. `help`: Link to context-sensitive help. `license`: Indicates that the main content of the current document is covered by the copyright license described by the referenced document. `me`: Indicates that the current document represents the person who owns the linked content. `next`: Indicates that the current document is part of a series and the next document in the series is the referenced document. `nofollow`: Indicates that the current document's original author or publisher does not endorse the referenced document. `noreferrer`: No `Referer` header will be included. Also has the same effect as `noopener`. `opener`: Creates an auxiliary browsing context if the hyperlink would otherwise create a top-level browsing context that is not an auxiliary browsing context (i.e., has "`_blank`" as `target` attribute value). `prev`: Indicates that the current document is part of a series and the previous document in the series is the referenced document. `search`: Links to a resource that can be used to search through the current document and its related pages. `tag`: Gives a tag (identified by the given address) that applies to the current document. Note: This is only available when `href` is specified.
`autofocus`	`autofocus`	`boolean`	`false`
Determines if the element should be focused when the page loads.
`tabindex`	`tabIndex`	`number`	-
Specifies the order in which the element receives focus when navigating with the Tab key.

Methods

Name	Parameters	Returns
`click`		`void`
Simulates a mouse click on the element.
`focus`	`options: FocusOptions` (Optional)	`void`
Sets focus on the element. An optional parameter can be an object with a `preventScroll` property. If `preventScroll` is set to `true`, the page will not scroll to bring the focused element into view.
`blur`		`void`
Removes focus from the element.

Events

Name
`focus`
Emitted when the list item gains focus.
`blur`
Emitted when the list item loses focus.

Slots

Name
(default)
Main text.
`description`
Subtext.
`icon`
Element on the left of the list item.
`end-icon`
Element on the right of the list item.
`custom`
Any custom content.

CSS Parts

Name
`container`
List item container.
`icon`
Left icon.
`end-icon`
Right icon.
`body`
Middle part.
`headline`
Main title.
`description`
Subtitle.

CSS Custom Properties

Name
`--shape-corner`
The size of the component corner. You can use a specific pixel value, but it's recommended to reference design tokens.
`--shape-corner-rounded`
The size of the component corner when `rounded` is specified. You can use a specific pixel value, but it's recommended to reference design tokens.

`mdui-list-subheader` API

Slots

Name
(default)
Subheader text.

`mdui-list` API

Slots

Name
(default)
Contains `<mdui-list-item>` elements.

LinearProgress

Up Next