Winnie CSS
  1. Primitives
  2. listbox

listbox

A list of options that allows a user to optionally select one or more of them.

  • Edit
  • Duplicate
  • Share 
<ul data-component="listbox">
  <li data-component="listbox-item">
    <span data-slot="label">Edit</span>
  </li>
  <li data-component="listbox-item">
    <span data-slot="label">Duplicate</span>
  </li>
  <div data-component="separator"></div>
  <li data-component="listbox-item">
    <span data-slot="label">Archive</span>
  </li>
</ul>

Import

Import just the listbox styles.

@import "@winnie-ui/css/spatial/listbox";
@import "@winnie-ui/css/visual/listbox";

Anatomy

Attach the appropriate data attributes in the structure below.

<ul data-component="listbox">
  <li data-component="listbox-item">
    <span data-slot="label"></span>
  </li>
  <div data-component="separator"></div>
  <section data-component="section">
    <header data-slot="header">
      <span data-slot="label"></span>
    </header>
    <li data-component="listbox-item">
      <i data-slot="indicator"></i>
      <span data-slot="label"></span>
    </li>
    <li data-component="listbox-item">
      <i data-slot="icon"></i>
      <span data-slot="label"></span>
    </li>
    <li data-component="listbox-item">
      <span data-slot="label"></span>
      <kbd data-slot="shortcut"></kbd>
    </li>
  </section>
</ul>

Examples

Size

Use the data-size attribute to change the size.

  • Edit
  • Duplicate
  • Share
  • Edit
  • Duplicate
  • Share
  • Edit
  • Duplicate
  • Share 
<ul data-component="listbox" data-size="<size>">
  ...
</ul>

Radius

Use the data-radius attribute to change the size.

  • Edit
  • Duplicate
  • Share
  • Edit
  • Duplicate
  • Share
  • Edit
  • Duplicate
  • Share
  • Edit
  • Duplicate
  • Share
  • Edit
  • Duplicate
  • Share 
<ul data-component="listbox" data-radius="<radius>">
  ...
</ul>

Color

Use the data-accent-color attribute to change the color a specific item.

  • Edit
  • Duplicate
  • Share
  • Delete 
<ul data-component="listbox">
  ...
  <li data-component="listbox-item" data-accent-color="red">
    <span data-slot="label">Delete</span>
  </li>
</ul>

Separator

Add a separator using the separator component.

  • Edit
  • Duplicate
  • Share
  • Delete 
<ul data-component="listbox">
  ...
  <div data-component="separator" />
  ...
</ul>

Icon

Add an icon to an item using the icon slot attribute as a child of a list item.

  • Edit
  • Duplicate
  • Share
  • Delete 
<ul data-component="listbox">
  ...
  <li data-component="listbox-item">
    <i data-slot="icon" class="trash-can"></i>
    <span data-slot="label">Delete</span>
  </li>
</ul>

Sections

Use the section, header, and separator attributes to group items.

    Manage
  • Status
  • Group
  • Labels
    • Actions
  • Edit
  • Duplicate
  • Share
  • Delete 
<ul data-component="listbox">
  <section data-component="listbox-section">
    <header data-component="listbox-header">
      <span data-slot="label">User Settings</span>
    </header>
    ...
  </section>
</ul>

Indicators

Add an icon or checkbox to indicate that an item has been selected using the indicator slot as a child of a list item. Note, if you want to reduce layout shift when using indicators that dynamically render on selection, see Mode.

  • Pepperoni
  • Sausage
  • Ham
  • Green Pepper
  • Olives
  • Pineapple
  • Pepperoni
  • Sausage
  • Ham
  • Green Pepper
  • Olives
  • Pineapple
  • Pepperoni
  • Sausage
  • Ham
  • Green Pepper
  • Olives
  • Pineapple 
<ul data-component="listbox">
  ...
  <li data-component="listbox-item">
    <i data-slot="indicator"></i>
    <span data-slot="label">Thin</span>
  </li>
  ...
</ul>

Mode

Use the data-mode attribute to account for dynamically rendered indicators. This allows you to avoid layout shift in components that could potentially transition from having zero items selected to one or more.

  • Thin
  • Pan
  • Gluten-free 
<ul data-component="listbox" data-mode="selection">
  ...
</ul>

Descriptions

Use the description slot in different variations to achieve the layout that works for your use case.

Column

You can create a column layout with the help of listbox-group component and placing the label and description slots as children.

  • Read Read only
  • Write Read and write only
  • Admin Full access 
<ul data-component="listbox">
  <li data-component="listbox-item">
    <i data-slot="indicator"></i>
    <div data-component="listbox-group">
      <span data-slot="label">Read</span>
      <span data-slot="description">Read only</span>
    </div>
  </li>
  ...
</ul>

Row

Simlar to the column layout, you can create a row based layout with staggared alignment using the listbox-group component.

  • Read Read only
  • Write Read and write only
  • Admin Full access 
<ul data-component="listbox">
  <li data-component="listbox-item">
    <i data-slot="indicator"></i>
    <div data-component="listbox-group" data-orientation="row">
      <span data-slot="label">Read</span>
      <span data-slot="description">Read only</span>
    </div>
  </li>
  ...
</ul>

Inline

Finally, if you prefer to align all descriptions, you can skip the group component and provide the description slot as a child of listbox-item.

  • Read Read only
  • Write Read and write only
  • Admin Full access 
<ul data-component="listbox">
  <i data-slot="indicator"></i>
  <li data-component="listbox-item">
    <span data-slot="label">Read</span>
    <span data-slot="description">Read only</span>
  </li>
  ...
</ul>

Shortcuts

Use the shortcut slot as a child of the list item to show a keyboard shortcut.

  • Edit E
  • Duplicate D
  • Share S
  • Delete ⌘ D 
<ul data-component="listbox">
  ...
  <li data-component="listbox-item">
    <span data-slot="label">Delete</span>
    <kbd data-slot="shortcut">
      <kbd data-component="kbd">⌘</kbd>
      <kbd data-component="kbd">D</kbd>
    </kbd>
  </li>
</ul>

Disabled

Use the data-disabled or aria-disabled attribute to prevent user iteraction.

  • Edit E
  • Duplicate D
  • Share S
  • Delete ⌘ D 
<ul data-component="listbox">
  ...
  <li data-component="listbox-item" data-disabled="true">
    <span data-slot="label">Delete</span>
    <kbd data-slot="shortcut">
      <kbd data-component="kbd">⌘</kbd>
      <kbd data-component="kbd">D</kbd>
    </kbd>
  </li>
</ul>

Reference

listbox

Groups all of the parts of the listbox item together.

AttributeValue
data-accent-color"red" | "orange" | "yellow" | "green" | "blue" | "purple" | "pink" | "grey" | "brand"
data-radius"none" | "sm" | "md" | "lg" | "round"
data-size"sm" | "md" | "lg"

section-header

Represents the header of a listbox section.

Variable
--wui-listbox-section-header-label-color
--wui-listbox-section-header-label-font-weight

listbox-item

Groups all of the parts of the listbox item together.

AttributeValue
data-accent-color"red" | "orange" | "yellow" | "green" | "blue" | "purple" | "pink" | "grey" | "brand"
data-disabledboolean
data-radius"none" | "sm" | "md" | "lg" | "round"
data-size"sm" | "md" | "lg"
ModifierDescription
hoveredWhen the listbox-item is hovered with a mouse
pressedWhen the listbox-item is pressed with a mouse or keyboard
disabledWhen the listbox-item prevents user interaction
Variable
--wui-listbox-item-background-<?modifier>
--wui-listbox-item-border-<?modifier>
--wui-listbox-item-box-shadow-<?modifier>
--wui-listbox-item-color-<?modifier>
--wui-listbox-item-shortcut-color-<?modifier>
--wui-listbox-item-group-label-color
--wui-listbox-item-group-label-font-weight
--wui-listbox-item-group-description-color
--wui-listbox-item-group-description-font-weight