# List Component

A list is a vertical collection of items that can contain text or images.

## Usage {#usage}

Import the component:

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

Import the TypeScript type:

```ts
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:

```html
<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 {#examples}

### Text Content {#example-text}

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

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

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

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

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.

```html
<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>
```

### Side Content {#example-side}

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

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

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

```html
<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>
```

### Link {#example-link}

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

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

### Disabled State {#example-disabled}

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

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

### Active State {#example-active}

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

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

### Nonclickable State {#example-nonclickable}

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

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

### Rounded Shape {#example-rounded}

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

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

### Vertical Alignment {#example-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.

```html
<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>
```

### Custom Content {#example-custom}

The `custom` slot in `<mdui-list-item>` lets you fully customize the list item content.

```html
<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>
```

## mdui-list-item API

### Properties

<table>
<thead>
  <tr>
    <th>Attribute</th>
    <th>Property</th>
    <th>Reflect</th>
    <th>Type</th>
    <th>Default</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>headline</td>
    <td>headline</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Main text. Alternatively, use the default slot.</p>
</td>
  </tr>
  <tr>
    <td>headline-line</td>
    <td>headlineLine</td>
    <td>true</td>
    <td>1 | 2 | 3</td>
    <td></td>
    <td><p>Maximum number of lines for the main text. Overflow text is truncated. Default is no limit. Possible values:</p>
<ul>
<li><code>1</code>: Single-line text that truncates when it overflows.</li>
<li><code>2</code>: Two-line text that truncates when it overflows.</li>
<li><code>3</code>: Three-line text that truncates when it overflows.</li>
</ul>
</td>
  </tr>
  <tr>
    <td>description</td>
    <td>description</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Subtext. Alternatively, use <code>slot=&quot;description&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>description-line</td>
    <td>descriptionLine</td>
    <td>true</td>
    <td>1 | 2 | 3</td>
    <td></td>
    <td><p>Maximum number of lines for the subtext. Overflow text is truncated. Default is no limit. Possible values:</p>
<ul>
<li><code>1</code>: Single-line text that truncates when it overflows.</li>
<li><code>2</code>: Two-line text that truncates when it overflows.</li>
<li><code>3</code>: Three-line text that truncates when it overflows.</li>
</ul>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td>icon</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Material Icons name on the left. Alternatively, use <code>slot=&quot;icon&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>end-icon</td>
    <td>endIcon</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Material Icons name on the right. Alternatively, use <code>slot=&quot;end-icon&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>disabled</td>
    <td>disabled</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Disables the list item. It dims the item and disables interactive elements like <a href="/en/docs/2/components/checkbox"><code>&lt;mdui-checkbox&gt;</code></a>, <a href="/en/docs/2/components/radio"><code>&lt;mdui-radio&gt;</code></a>, and <a href="/en/docs/2/components/switch"><code>&lt;mdui-switch&gt;</code></a>.</p>
</td>
  </tr>
  <tr>
    <td>active</td>
    <td>active</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Marks the list item as active.</p>
</td>
  </tr>
  <tr>
    <td>nonclickable</td>
    <td>nonclickable</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Disables the list item&#39;s default click action, but interactive elements like <a href="/en/docs/2/components/checkbox"><code>&lt;mdui-checkbox&gt;</code></a>, <a href="/en/docs/2/components/radio"><code>&lt;mdui-radio&gt;</code></a>, and <a href="/en/docs/2/components/switch"><code>&lt;mdui-switch&gt;</code></a> inside it remain functional.</p>
</td>
  </tr>
  <tr>
    <td>rounded</td>
    <td>rounded</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Applies a rounded appearance to the list item.</p>
</td>
  </tr>
  <tr>
    <td>alignment</td>
    <td>alignment</td>
    <td>true</td>
    <td>&#39;start&#39; | &#39;center&#39; | &#39;end&#39;</td>
    <td>'center'</td>
    <td><p>Vertical alignment of the list item. Possible values:</p>
<ul>
<li><code>start</code>: Aligns to the top.</li>
<li><code>center</code>: Aligns to the center.</li>
<li><code>end</code>: Aligns to the bottom.</li>
</ul>
</td>
  </tr>
  <tr>
    <td>href</td>
    <td>href</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>The URL for the link. When set, the component renders as an <code>&lt;a&gt;</code> element and supports link-related attributes.</p>
</td>
  </tr>
  <tr>
    <td>download</td>
    <td>download</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Downloads the linked URL.</p>
<p><strong>Note</strong>: Only available when <code>href</code> is specified.</p>
</td>
  </tr>
  <tr>
    <td>target</td>
    <td>target</td>
    <td>true</td>
    <td>&#39;_blank&#39; | &#39;_parent&#39; | &#39;_self&#39; | &#39;_top&#39;</td>
    <td></td>
    <td><p>Controls where the linked URL opens. Possible values:</p>
<ul>
<li><code>_blank</code>: Opens in a new tab or window.</li>
<li><code>_parent</code>: Opens in the parent browsing context, or <code>_self</code> if there is no parent.</li>
<li><code>_self</code>: Opens in the current browsing context (default).</li>
<li><code>_top</code>: Opens in the topmost browsing context, or <code>_self</code> if there are no ancestors.</li>
</ul>
<p><strong>Note</strong>: Only available when <code>href</code> is specified.</p>
</td>
  </tr>
  <tr>
    <td>rel</td>
    <td>rel</td>
    <td>true</td>
    <td>&#39;alternate&#39; | &#39;author&#39; | &#39;bookmark&#39; | &#39;external&#39; | &#39;help&#39; | &#39;license&#39; | &#39;me&#39; | &#39;next&#39; | &#39;nofollow&#39; | &#39;noreferrer&#39; | &#39;opener&#39; | &#39;prev&#39; | &#39;search&#39; | &#39;tag&#39;</td>
    <td></td>
    <td><p>Specifies the relationship of the linked URL as space-separated link types. Possible values:</p>
<ul>
<li><code>alternate</code>: An alternate version of the current document.</li>
<li><code>author</code>: The author of the current document or article.</li>
<li><code>bookmark</code>: The permalink for the nearest ancestor section.</li>
<li><code>external</code>: The referenced document is not part of the same site as the current document.</li>
<li><code>help</code>: A link to context-sensitive help.</li>
<li><code>license</code>: Content covered by the copyright license described by the referenced document.</li>
<li><code>me</code>: Links to content owned by the current document&#39;s author.</li>
<li><code>next</code>: The next document in the series.</li>
<li><code>nofollow</code>: Not endorsed by the original author or publisher.</li>
<li><code>noreferrer</code>: Prevents the <code>Referer</code> header from being sent. Same effect as <code>noopener</code>.</li>
<li><code>opener</code>: Creates a new browsing context when the hyperlink would otherwise open in a top-level context that is not auxiliary (for example, when <code>target=&quot;_blank&quot;</code> is specified).</li>
<li><code>prev</code>: The previous document in the series.</li>
<li><code>search</code>: Links to a resource that can be used to search through the current document and its related pages.</li>
<li><code>tag</code>: Marks the current document with the given tag.</li>
</ul>
<p><strong>Note</strong>: Only available when <code>href</code> is specified.</p>
</td>
  </tr>
  <tr>
    <td>autofocus</td>
    <td>autofocus</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Whether the element is focused when the page loads.</p>
</td>
  </tr>
  <tr>
    <td>tabindex</td>
    <td>tabIndex</td>
    <td>false</td>
    <td>number</td>
    <td></td>
    <td><p>The element&#39;s tab order when navigating with the Tab key.</p>
</td>
  </tr>
</tbody>
</table>

### Methods

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>click(): void</td>
    <td><p>Simulates a mouse click on the element.</p>
</td>
  </tr>
  <tr>
    <td>focus(options?: FocusOptions): void</td>
    <td><p>Sets focus on the element. An optional object parameter may include a <code>preventScroll</code> property. If <code>preventScroll</code> is set to <code>true</code>, the page will not scroll to bring the focused element into view.</p>
</td>
  </tr>
  <tr>
    <td>blur(): void</td>
    <td><p>Removes focus from the element.</p>
</td>
  </tr>
</tbody>
</table>

### Events

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>focus</td>
    <td><p>Emitted when the list item gains focus.</p>
</td>
  </tr>
  <tr>
    <td>blur</td>
    <td><p>Emitted when the list item loses focus.</p>
</td>
  </tr>
</tbody>
</table>

### Slots

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>(default)</td>
    <td><p>Main text.</p>
</td>
  </tr>
  <tr>
    <td>description</td>
    <td><p>Subtext.</p>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td><p>Element on the left of the list item.</p>
</td>
  </tr>
  <tr>
    <td>end-icon</td>
    <td><p>Element on the right of the list item.</p>
</td>
  </tr>
  <tr>
    <td>custom</td>
    <td><p>Any custom content.</p>
</td>
  </tr>
</tbody>
</table>

### CSS Parts

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>container</td>
    <td><p>List item container.</p>
</td>
  </tr>
  <tr>
    <td>icon</td>
    <td><p>Left icon.</p>
</td>
  </tr>
  <tr>
    <td>end-icon</td>
    <td><p>Right icon.</p>
</td>
  </tr>
  <tr>
    <td>body</td>
    <td><p>Middle section.</p>
</td>
  </tr>
  <tr>
    <td>headline</td>
    <td><p>Main title.</p>
</td>
  </tr>
  <tr>
    <td>description</td>
    <td><p>Subtitle.</p>
</td>
  </tr>
</tbody>
</table>

### CSS Custom Properties

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>--shape-corner</td>
    <td><p>The corner radius of the component. You can use a specific pixel value, but it is recommended to reference <a href="/en/docs/2/styles/design-tokens#shape-corner">design tokens</a>.</p>
</td>
  </tr>
  <tr>
    <td>--shape-corner-rounded</td>
    <td><p>The corner radius of the component when <code>rounded</code> is specified. You can use a specific pixel value, but it is recommended to reference <a href="/en/docs/2/styles/design-tokens#shape-corner">design tokens</a>.</p>
</td>
  </tr>
</tbody>
</table>

## mdui-list-subheader API

### Slots

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>(default)</td>
    <td><p>Subheader text.</p>
</td>
  </tr>
</tbody>
</table>

## mdui-list API

### Slots

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>(default)</td>
    <td><p>Contains <code>&lt;mdui-list-item&gt;</code> elements.</p>
</td>
  </tr>
</tbody>
</table>