List

A list is a vertical collection 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>

Source

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>

Source

By default, both primary and secondary text are shown in full. To limit the number of lines, use the headline-line and description-line attributes. The maximum 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>

Source

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>

Source

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>

Source

Link

The href attribute turns the list item 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>

Source

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>

Source

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>

Source

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>

Source

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>

Source

Vertical Alignment

The alignment attribute on <mdui-list-item> controls the vertical alignment of side elements. Possible values:

start: align to the top.
center: center aligned.
end: align to the bottom.

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>

Source

Custom Content

The custom slot in <mdui-list-item> lets you fully customize 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>

Source

`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`	-
Maximum number of lines for the main text. Overflow text is truncated. Default is no limit. Possible values: `1`: Single-line text that truncates when it overflows. `2`: Two-line text that truncates when it overflows. `3`: Three-line text that truncates when it overflows.
`description`	`description`	`string`	-
Subtext. Alternatively, use `slot="description"`.
`description-line`	`descriptionLine`	`1 \| 2 \| 3`	-
Maximum number of lines for the subtext. Overflow text is truncated. Default is no limit. Possible values: `1`: Single-line text that truncates when it overflows. `2`: Two-line text that truncates when it overflows. `3`: Three-line text that truncates when it overflows.
`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. It dims the item and disables interactive elements like `<mdui-checkbox>`, `<mdui-radio>`, and `<mdui-switch>`.
`active`	`active`	`boolean`	`false`
Marks the list item as active.
`nonclickable`	`nonclickable`	`boolean`	`false`
Disables the list item's default click action, but interactive elements like `<mdui-checkbox>`, `<mdui-radio>`, and `<mdui-switch>` inside it remain functional.
`rounded`	`rounded`	`boolean`	`false`
Applies a rounded appearance to the list item.
`alignment`	`alignment`	`'start' \| 'center' \| 'end'`	`'center'`
Vertical alignment of the list item. Possible values: `start`: Aligns to the top. `center`: Aligns to the center. `end`: Aligns to the bottom.
`href`	`href`	`string`	-
The URL for the link. When set, the component renders as an `<a>` element and supports link-related attributes.
`download`	`download`	`string`	-
Downloads the linked URL. Note: Only available when `href` is specified.
`target`	`target`	`'_blank' \| '_parent' \| '_self' \| '_top'`	-
Controls where the linked URL opens. Possible values: `_blank`: Opens in a new tab or window. `_parent`: Opens in the parent browsing context, or `_self` if there is no parent. `_self`: Opens in the current browsing context (default). `_top`: Opens in the topmost browsing context, or `_self` if there are no ancestors. Note: 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`: An alternate version of the current document. `author`: The author of the current document or article. `bookmark`: The permalink for the nearest ancestor section. `external`: The referenced document is not part of the same site as the current document. `help`: A link to context-sensitive help. `license`: Content covered by the copyright license described by the referenced document. `me`: Links to content owned by the current document's author. `next`: The next document in the series. `nofollow`: Not endorsed by the original author or publisher. `noreferrer`: Prevents the `Referer` header from being sent. Same effect as `noopener`. `opener`: Creates a new browsing context when the hyperlink would otherwise open in a top-level context that is not auxiliary (for example, when `target="_blank"` is specified). `prev`: The previous document in the series. `search`: Links to a resource that can be used to search through the current document and its related pages. `tag`: Marks the current document with the given tag. Note: Only available when `href` is specified.
`autofocus`	`autofocus`	`boolean`	`false`
Whether the element is focused when the page loads.
`tabindex`	`tabIndex`	`number`	-
The element's tab order 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 object parameter may include 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 section.
`headline`
Main title.
`description`
Subtitle.

CSS Custom Properties

Name
`--shape-corner`
The corner radius of the component. You can use a specific pixel value, but it is recommended to reference design tokens.
`--shape-corner-rounded`
The corner radius of the component when `rounded` is specified. You can use a specific pixel value, but it is 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