Component proposal: List

[janhassel]

List

Overview

A list is a structured way to display grouped information. The individual list items can contain static / read-only information as well as being interactive. A list is preceded by the list header, which always contains the title for a group of list items and can optionally hold additional, supporting information or interactive elements.

When to use

• Items can be logically grouped
• Items follow the same structure
• Items are simple and can be displayed in a compact format

When not to use

• Items don't have a relation to each other
• Items vary in format and structure
• Items contain complex interactions or should be displayed in larger sizes

Variants

Variant	Purpose
Default	When the list is placed as a normal part of the user interface, like on a tile or in a sidebar.
Compact	When the list is placed within a temporary context, like a popover. The list must span the entire width of the parenting element and the parenting element must either have an outer border or shadow to visually separate its content from the rest of the user interface.

Default

Compact

Formatting

Anatomy

1. List header: Is used to group the succeeding list items.
2. List title: Gives the list group a descriptive name.
3. Additional list header content (optional): Can contain supporting information or interactive elements for this list group.
4. List item: An entry of the list. The content is completely flexible.

Universal behaviours

The behaviors listed in this section are universal across all of the types. For behaviors that are unique to each type, see each of the component type sections below.

States

• If a list item is interactive, it should follow the interactive states of the Tile component in regards to hover, active and focus.

Interactions

• A list header is always visible for as long as its associated list items are visible on the screen. To achieve this, the list header sticks to the top of its parenting element and only allows itself to be pushed by a succeeding list header or a new element which is scrolled into view.
• In case a list item is interactive or has interactive elements, each interaction should be a tabstop. Keep the number of interactions to a minimum. Remember: if a list item is too cmplex or benefits from a larger area, the list component is probably not the right choice. Consider using headings to organize your content.

Style

• Ensure that all list items within a list are the same height to avoid visual discordance

---

Examples

Default variant

Default variant

To anyone on the Carbon team, please feel free to reach out via Slack so we can talk about more use cases and examples I can't post here. Also, I'd be more than happy to share the interactiv prototypes.
@aagonzales @joshblack @laurenmrice @sstrubberg

Additional notes

• This component might need a better name to differenatiate it from UnorderedList and OrderedList (and their shared ListItem child component).
• The "Compact" variant name might be misleading and could lead to issues when the component is expanded to support multiple sizes (like sm, md, lg).

[aagonzales]

I've been thinking about what the differences are between your list (which is great) and the existing simple structured list.

Some of the differences I'm seeing are:

• Jan's list only has 1 column header, not multiple columns. (Though can have sub-items on the right side in addition to the left side).
• Jan's list can have inline actions instead of row actions like structured list.
• The example shown above are all flush to a containers edge, structured list can sit flat on a page without a structure.
• Jan's list is more a traditional list vs structured list is more table like.

I'm basically just trying to figure out if this is a wholesale new component or if its a new variant of either list or structured list components.

[janhassel]

I think a big difference and probably a reason to treat it as a separate component is that the individual list items are fully customizable by the team. It's more of a grouping design pattern than an enumeration of things I believe.

From the current research, the only aspects the list items should always share regardless of the actual implementtion by the team are:

• Background
• Dividing line underneath at the bottom
• If interactive: hover, focus and active state

[joshblack]

Looks great to me 🎉

[janhassel]

I think to move this forward, we'd need to...

1. define a name for the component (and its two variants)
2. create design specs for spacing, color and typography (I'd be glad to share the specs I've used so far for above mockups, probably don't need to start from scratch)
3. build out an experimental version of this component (I can definitely help out here as I have a coded prototype of this and could work on porting it over)

@aagonzales What do you think?

[dianasanborn]

We have a list component within AI Apps that's used for the exact same use cases above and more.

Note: The guidance we have on the site was carried over from the former IoT PAL, and needs to be fully revisited to follow the Carbon guidance structure and also evolved design and use cases, but you can get an idea of the additional variations we have.

You can see how it gets used in other patterns, like a list builder. This is a link to our coded implementation of it as well.

Would love to contribute and collaborate on this as well if it's being picked up at the Carbon level! We have a lot of use cases for it.

[laurenmrice]

Contained list

• Code: Contained list will be it's own component the the React story book.
• Design: Contained list will be housed under an overarching List category with Unordered list, Ordered list, and Structured list in docs.
• Names of Variants 1 and 2 are still TBD.

---

Variant 1 (color and type tokens)

Variant 1 (specs)

---

Variant 2 (color and type tokens)

Variant 2 (specs)