material-inspired-component-library

Version:

The Material-Inspired Component Library (MICL) offers a collection of beautifully crafted components leveraging native HTML markup, designed to align with the Material Design 3 guidelines.

github.com/henkpb/micl

henkpb/micl

205 lines (171 loc) • 7.88 kB

Markdown

# List This component implements the the [Material Design 3 Expressive List](https://m3.material.io/components/lists/overview) design. Lists are continuous, vertical groups of text or images, representing a set of data. ## Basic Usage ### HTML To create a basic list, use the `<ul>` element with the `micl-list` class and individual `<li>` elements for each list item. For a basic single-line item, use the `micl-list-item-one` class: ```HTML <ul class="micl-list" role="listbox"> <li class="micl-list-item-one" tabindex="0"> A single-line item </li> </ul> ``` - The `role="listbox"` is used for accessibility, indicating a selectable list. - `tabindex="0"` on the `<li>` makes the list item focusable and allows keyboard navigation. ### CSS Import the list styles into your project: ```CSS @use "material-inspired-component-library/dist/list"; ``` ### JavaScript This component requires JavaScript to support keyboard navigation: ```JavaScript import micl from "material-inspired-component-library/dist/micl"; ``` This will initialize any List component, including those that will be added to the DOM later on. ### Demo A live example of the [List component](https://henkpb.github.io/micl/list.html) is available for you to interact with. ## Variants The List component offers three CSS classes to control the height and content capacity of individual list items: | CSS class | Description | | --------- | ----------- | | micl-list-item-one | For single-line items, accommodating one line of text. | | micl-list-item-two | For two-line items, accommodating up to two lines of text. | | micl-list-item-three | For three-line items, accommodating up to three lines of text. | ```HTML <ul class="micl-list" role="listbox"> <li class="micl-list-item-three" tabindex="0"> A three-line item Supporting text that is long enough to fill up multiple lines of text with words and sentences. </li> </ul> ``` Use the anchor element to convert a list item into a hyperlink: ```HTML <ul class="micl-list" role="listbox"> <li class="micl-list-item-one" tabindex="0"> <a href="https://www.thetimes.com" tabindex="-1"> The Times </a> </li> </ul> ``` Adding the `micl-list-item--disabled` class to the `<li>` element causes the list item to be displayed in a disabled state. Add the `micl-list__divider` class to the `<ul>` element to automatically place a divider between each list item. ### Leading Content The text content of a list item can be preceded by various media elements: - **Icon**: Use `micl-list-item__icon` with a (Material Symbols) icon. ```HTML <li class="micl-list-item-two" tabindex="0"> person Bill Jones bill.jones@email.com </li> ``` - **Avatar**: Use `micl-list-item__avatar` with a text. ```HTML <li class="micl-list-item-two" tabindex="0"> BJ Bill Jones bill.jones@email.com </li> ``` - **Image**: Use `micl-list-item__image` with a background image. ```HTML <li class="micl-list-item-two" tabindex="0"> Bill Jones bill.jones@email.com </li> ``` - **Thumbnail (Video)**: Use `micl-list-item__thumbnail` for video previews with a background-image. ```HTML <li class="micl-list-item-two" tabindex="0"> Bill Jones Short clip of Bill </li> ``` ### Trailing Content The text of a list item may be followed by a trailing text, imagery or other elements (like a checkbox). - **Icon**: Use `micl-list-item__icon` with a (Material Symbols) icon. ```HTML <li class="micl-list-item-two" tabindex="0"> Date and time Timezones, calendar display more_horiz </li> ``` - **Text**: Use `micl-list-item__trailing-text` with a short text. ```HTML <li class="micl-list-item-one" tabindex="0"> To-do items 100+ </li> ```` ### Selecting List Items To enable selection of list items, integrate a checkbox or switch component within the `<li>` element. ```HTML <ul class="micl-list micl-list__divider" role="listbox"> <li class="micl-list-item-two" tabindex="0"> <label> Blue car A blue car with four wheels. </label> <input type="checkbox" id="mycheckbox" class="micl-checkbox" value="cb1" tabindex="-1"> </li> <li class="micl-list-item-two" tabindex="0"> <label> Red car A red car with tinted windows. </label> <input type="checkbox" id="checkbox2" class="micl-switch" value="cb2" tabindex="-1"> </label> </li> </ul> ``` - `tabindex="-1"` on the `input` is important here, as the `<li>` should handle the focus for accessibility. ## Customizations You can customize the appearance of the List component by overriding its global CSS variables. These variables are declared on the `:root` pseudo-class and can be changed on any appropriate parent element to affect its child lists. | Variable name | Default Value | Description | | ------------- | ------------- | ----------- | | --md-sys-list-item-one-height | 56px | The height for a single-line list item. | | --md-sys-list-item-two-height | 72px | The height for a two-line list item. | | --md-sys-list-item-three-height | 88px | The height for a three-line list item. | | --md-sys-list-item-one-padding | 8px | The vertical padding of a single-line list item. | | --md-sys-list-item-two-padding | 8px | The vertical padding of a two-line list item. | | --md-sys-list-item-three-padding | 12px | The vertical padding of a three-line list item. | | --md-sys-list-item-space | 16px | The horizontal spacing between the elements within a list item. | **Example: Changing the height of single-line list items** ```HTML <div style="--md-sys-list-item-one-height:60px"> <ul class="micl-list"> <li class="micl-list-item-one" tabindex="0"> A single-line item </li> </ul> </div> ```