<!-- AUTO-GENERATED from the @riverty/web-components custom elements manifest. Do not edit by hand. -->

# r-list-item

A single interactive list item with configurable leading icon, headline, description, trailing area, and support for nested child items.

Example
```html
<r-list-item headline="Account settings" description="Manage your account preferences">
  <r-icon slot="leading" name="user" size="m"></r-icon>
  <r-icon slot="trailing" name="arrow-right" size="m"></r-icon>
</r-list-item>

<!-- With nested items -->
<r-list-item headline="Documents">
  <r-list-item headline="Invoices"></r-list-item>
  <r-list-item headline="Contracts"></r-list-item>
</r-list-item>
```

## class: `RListItem`, `r-list-item`

### Fields

| Name                   | Privacy | Type                                                 | Default       | Description                                                                                                                        | Inherited From |
| ---------------------- | ------- | ---------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| `active`               |         | `boolean`                                            |               | Indicates whether the list item is currently active (e.g., represents the current page).                                           |                |
| `alignment`            |         | `"bottom" \| "center" \| "top"`                      |               | Defines the alignment style for the trailing text.                                                                                 |                |
| `checkbox`             |         | `boolean`                                            |               | If true, renders a checkbox in the trailing slot (3rd slot).                                                                       |                |
| `checked`              |         | `boolean`                                            | `false`       | Controls the checked state of the trailing checkbox.                                                                               |                |
| `description`          |         | `string`                                             |               | Secondary text displayed below the headline (2nd slot), used for additional details or context.                                    |                |
| `disabled`             |         | `boolean`                                            |               | If true, prevents user interaction with the list item and applies a disabled style.                                                |                |
| `divider`              |         | `boolean`                                            |               | If true, adds a horizontal divider below the list item.                                                                            |                |
| `expanded`             |         | `boolean`                                            | `false`       | Determines whether the list item is expanded to show its subitems. It can be toggled programmatically or through user interaction. |                |
| `form`                 |         | `string`                                             |               | Specifies the `id` of the `<form>` to which the element belongs                                                                    |                |
| `headline`             |         | `string`                                             |               | The main text or headline displayed in the text slot (2nd slot) of the list item.                                                  |                |
| `hideLeadingIcon`      |         | `boolean`                                            |               | Defines if the leading icon shall become hidden.                                                                                   |                |
| `href`                 |         | `string`                                             |               | If provided, renders the list item as a link using the <a> tag with the given href attribute.                                      |                |
| `indeterminate`        |         | `boolean`                                            | `false`       | Controls the indeterminate state of the trailing checkbox.                                                                         |                |
| `interactive`          |         | `boolean`                                            |               | Indicates that element is supports accessible interactions, like hover, focus, click, etc.                                         |                |
| `invalid`              |         | `boolean`                                            |               | Indicate that validation has failed                                                                                                |                |
| `leadingIcon`          |         | `string`                                             |               | Specifies the name of the icon to display in the leading slot (1st slot) of the list item.                                         |                |
| `leadingIconSrc`       |         | `string`                                             |               | Defines an icon source to be presented in leading slot                                                                             |                |
| `name`                 |         | `string`                                             |               | Controls the name of the trailing checkbox, used for form submission.                                                              |                |
| `novalidate`           |         | `boolean`                                            |               | Specifies if element must be ignored during validation of the form elements                                                        |                |
| `position`             |         | `"center" \| "top"`                                  | `'center'`    | Controls the position of the trailing checkbox.                                                                                    |                |
| `required`             |         | `boolean`                                            |               | Specifies if checkbox must be checked                                                                                              |                |
| `trailingBadge`        |         | `string`                                             |               | Badge text displayed in the trailing slot (3rd slot), as an alternative to an icon or text.                                        |                |
| `trailingBadgeVariant` |         | `"error" \| "information" \| "success" \| "warning"` |               | Badge variant displayed in the trailing slot (3rd slot), as an alternative to an icon or text.                                     |                |
| `trailingIcon`         |         | `string`                                             |               | Specifies the name of the icon to display in the trailing slot (3rd slot) of the list item.                                        |                |
| `trailingIconSrc`      |         | `string`                                             |               | Defines an icon source to be presented in trailing slot                                                                            |                |
| `trailingText`         |         | `string`                                             |               | Text displayed in the trailing slot (3rd slot), as an alternative to an icon.                                                      |                |
| `truncateDescription`  |         | `boolean`                                            |               | When enabled, the description is limited to a single line and truncated with an ellipsis if it overflows.                          |                |
| `valid`                |         | `boolean`                                            |               | Indicate that validation is successful                                                                                             |                |
| `value`                |         | `string`                                             |               | Controls the value of the trailing checkbox, used for form submission.                                                             |                |
| `variant`              |         | `"list-item" \| "navitem" \| "subitem"`              | `'list-item'` | Controls the style variation of the list item, such as regular or subitem.                                                         |                |

### Methods

| Name                 | Privacy | Description                                                                                                                                                                                                                                                                    | Parameters | Return                        | Inherited From |
| -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ----------------------------- | -------------- |
| `check`              |         | Checks the checkbox element.                                                                                                                                                                                                                                                   |            | `Promise<void>`               |                |
| `checkValidity`      |         | Validates the checkbox without triggering UI and returns a boolean indicating its validity.                                                                                                                                                                                    |            | `Promise<boolean>`            |                |
| `clearIndeterminate` |         | Sets the indeterminate state of the checkbox element.                                                                                                                                                                                                                          |            | `Promise<void>`               |                |
| `getValidityState`   |         | Asynchronously retrieves the validity state of the checkbox.<br><br>This method updates the internal validity state and message by calling `getValidityStateData`<br>with the native element, and then returns an object containing the current validity state and message. |            | `Promise<{ state: string; }>` |                |
| `setBlur`            |         | Removes focus from the checkbox element.                                                                                                                                                                                                                                       |            | `Promise<void>`               |                |
| `setFocus`           |         | Sets focus on the checkbox element.                                                                                                                                                                                                                                            |            | `Promise<void>`               |                |
| `setIndeterminate`   |         | Sets the indeterminate state of the checkbox element.                                                                                                                                                                                                                          |            | `Promise<void>`               |                |
| `toggleChecked`      |         | Toggles the checked state of the checkbox element                                                                                                                                                                                                                              |            | `Promise<void>`               |                |
| `toggleSubitems`     |         | Method to toggle sub-items of the list-item                                                                                                                                                                                                                                    |            | `Promise<void>`               |                |
| `uncheck`            |         | Unchecks the checkbox element.                                                                                                                                                                                                                                                 |            | `Promise<void>`               |                |

### Events

| Name        | Type                                                                            | Description                                                           | Inherited From |
| ----------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------------- |
| `rBlur`     | `CustomEvent<any>`                                                              | Emitted when the button or link within list-item loses focus.         |                |
| `rChange`   | `CustomEvent<{ element: HTMLRListItemElement; value: any; checked: boolean; }>` | Emit custom `rChange` event when checkbox onChange event emitted *    |                |
| `rFocus`    | `CustomEvent<any>`                                                              | Emitted when the button or link within list-item receives focus.      |                |
| `rReset`    | `CustomEvent<{ element: HTMLRListItemElement; value: any; checked: boolean; }>` | Emits `rReset` when checkbox was reset to initial state by form reset |                |
| `rValidate` | `CustomEvent<{ state: string; }>`                                               | Emits event after each validation                                     |                |

### Attributes

| Name                     | Field                | Inherited From |
| ------------------------ | -------------------- | -------------- |
| `active`                 | active               |                |
| `alignment`              | alignment            |                |
| `checkbox`               | checkbox             |                |
| `checked`                | checked              |                |
| `description`            | description          |                |
| `disabled`               | disabled             |                |
| `divider`                | divider              |                |
| `expanded`               | expanded             |                |
| `form`                   | form                 |                |
| `headline`               | headline             |                |
| `hide-leading-icon`      | hideLeadingIcon      |                |
| `href`                   | href                 |                |
| `indeterminate`          | indeterminate        |                |
| `interactive`            | interactive          |                |
| `invalid`                | invalid              |                |
| `leading-icon`           | leadingIcon          |                |
| `leading-icon-src`       | leadingIconSrc       |                |
| `name`                   | name                 |                |
| `novalidate`             | novalidate           |                |
| `position`               | position             |                |
| `required`               | required             |                |
| `trailing-badge`         | trailingBadge        |                |
| `trailing-badge-variant` | trailingBadgeVariant |                |
| `trailing-icon`          | trailingIcon         |                |
| `trailing-icon-src`      | trailingIconSrc      |                |
| `trailing-text`          | trailingText         |                |
| `truncate-description`   | truncateDescription  |                |
| `valid`                  | valid                |                |
| `value`                  | value                |                |
| `variant`                | variant              |                |

### CSS Parts

| Name             | Description                                |
| ---------------- | ------------------------------------------ |
| `item`           | The root list item element                 |
| `leading`        | Leading icon or avatar area on the left    |
| `sub-items`      | Container for nested child list items      |
| `text`           | Text content area (headline + description) |
| `trailing`       | Trailing content area on the right         |
| `trailing-badge` | Trailing badge element                     |
| `trailing-text`  | Trailing text label                        |

### Slots

| Name          | Description                         |
| ------------- | ----------------------------------- |
|               | Nested child list items             |
| `description` | Custom description text             |
| `headline`    | Custom headline text                |
| `leading`     | Custom leading element (e.g. icon)  |
| `text`        | Full custom text area content       |
| `trailing`    | Custom trailing element (e.g. icon) |

<hr/>

## Exports

| Kind                        | Name          | Declaration | Module | Package |
| --------------------------- | ------------- | ----------- | ------ | ------- |
| `js`                        | `RListItem`   | RListItem   |        |         |
| `custom-element-definition` | `r-list-item` | RListItem   |        |         |