Skip to content

Listbox

<quiet-listbox> stable since 1.0

Listbox displays a list of options, allowing users to select one or more items from the available choices.

Listboxes follow the ARIA APG listbox pattern for accessibility. The listbox is labeled for assistive devices and listbox items are announced as options. To function more like native listboxes, the alternate selection model is used for keyboard interaction.

Bella Luna Meowy McGee Milo Mittens Oliver Pepper Shadow Simba Whiskers 
<quiet-listbox label="Our kittens" description="Select your new friends." multiple>
  <quiet-listbox-item value="1">Bella</quiet-listbox-item>
  <quiet-listbox-item value="2">Luna</quiet-listbox-item>
  <quiet-listbox-item value="3">Meowy McGee</quiet-listbox-item>
  <quiet-listbox-item value="4">Milo</quiet-listbox-item>
  <quiet-listbox-item value="5">Mittens</quiet-listbox-item>
  <quiet-listbox-item value="6">Oliver</quiet-listbox-item>
  <quiet-listbox-item value="7">Pepper</quiet-listbox-item>
  <quiet-listbox-item value="8">Shadow</quiet-listbox-item>
  <quiet-listbox-item value="9">Simba</quiet-listbox-item>
  <quiet-listbox-item value="10">Whiskers</quiet-listbox-item>
</quiet-listbox>

Examples Jump to heading

Labels and descriptions Jump to heading

You can use the label and description attributes to provide plain text labels and descriptions for the listbox. If you want to provide HTML, use the label and description slots instead.

Feline Friends For adoption information, visit our cat sanctuary. Whiskers (3 years old) Mittens (2 years old) Shadow (5 years old) 
<quiet-listbox>
  <span slot="label">Feline <strong>Friends</strong></span>
  <span slot="description">
    For adoption information, <a href="https://example.com/" target="_blank">visit our cat sanctuary</a>.
  </span>
  <quiet-listbox-item value="1">Whiskers (3 years old)</quiet-listbox-item>
  <quiet-listbox-item value="2">Mittens (2 years old)</quiet-listbox-item>
  <quiet-listbox-item value="3">Shadow (5 years old)</quiet-listbox-item>
</quiet-listbox>

Providing options Jump to heading

Create listbox options by adding <quiet-listbox-item> elements inside the listbox. Each item should have a value attribute that will be submitted with the form.

Feather Wand Laser Pointer Catnip Mouse Crinkle Tunnel Cardboard Box 
<quiet-listbox label="Favorite Cat Toys">
  <quiet-listbox-item value="feather">Feather Wand</quiet-listbox-item>
  <quiet-listbox-item value="laser">Laser Pointer</quiet-listbox-item>
  <quiet-listbox-item value="catnip">Catnip Mouse</quiet-listbox-item>
  <quiet-listbox-item value="tunnel">Crinkle Tunnel</quiet-listbox-item>
  <quiet-listbox-item value="box">Cardboard Box</quiet-listbox-item>
</quiet-listbox>

Listbox items can have structured content, too.

Feather Wand

Laser Pointer

Catnip Mouse

Crinkle Tunnel

Cardboard Box

 
<quiet-listbox label="Favorite Cat Toys" id="listbox__options">
  <quiet-listbox-item value="feather">
    <h4>Feather Wand</h4>
    <small aria-hidden="true">Interactive toy that mimics bird movements</small>
  </quiet-listbox-item>
  <quiet-listbox-item value="laser">
    <h4>Laser Pointer</h4>
    <small aria-hidden="true">Creates a moving red dot for cats to chase</small>
  </quiet-listbox-item>
  <quiet-listbox-item value="catnip">
    <h4>Catnip Mouse</h4>
    <small aria-hidden="true">Soft toy filled with enticing catnip</small>
  </quiet-listbox-item>
  <quiet-listbox-item value="tunnel">
    <h4>Crinkle Tunnel</h4>
    <small aria-hidden="true">Collapsible tunnel with crinkly material cats love</small>
  </quiet-listbox-item>
  <quiet-listbox-item value="box">
    <h4>Cardboard Box</h4>
    <small aria-hidden="true">Simple but beloved hiding spot for feline friends</small>
  </quiet-listbox-item>
</quiet-listbox>

<style>
  #listbox__options {
    &::part(listbox) {
      height: auto; 
    }

    h4 {
      font-size: 1.125rem;
      font-weight: var(--quiet-font-weight-semibold);
      line-height: 1.4;
      margin-block: 0;
    }

    quiet-listbox-item:state(selected) small {
      color: var(--quiet-primary-text-on-soft);
    }
  }
</style>

Avoid placing interactive elements such as buttons and links inside the listbox item, as this will hinder accessibility and can lead to unexpected behaviors.

Providing an initial value Jump to heading

Add the selected attribute to the listbox item you want to select initially. When using multiple, you can apply selected to more than one option.

Sunny Windowsill Human's Lap Middle of the Bed Computer Keyboard 
<quiet-listbox label="Favorite Nap Location">
  <quiet-listbox-item value="windowsill">Sunny Windowsill</quiet-listbox-item>
  <quiet-listbox-item value="lap" selected>Human's Lap</quiet-listbox-item>
  <quiet-listbox-item value="bed">Middle of the Bed</quiet-listbox-item>
  <quiet-listbox-item value="keyboard">Computer Keyboard</quiet-listbox-item>
</quiet-listbox>

Getting and setting the selection Jump to heading

Listboxes provide several properties for interacting with their selection state programmatically. Use the value property for getting/setting a single value. Use the selectedValues property for multiple values. If you need to get or set a list of selected <quiet-listbox-item> elements, use the selectedItems property.

Getting the selection Jump to heading

Use value to get a single value. To get all selected values, use selectedValues. If you need to get an array of DOM elements, use selectedItems. 

// Get the first selected value
const value = listbox.value;

// Get an array of all selected values
const values = listbox.selectedValues;

// Get an array of all selected listbox item elements
const items = listbox.selectedItems;

Setting the selection Jump to heading

Use value to set a single value. To set multiple values, use selectedValues. If you need to get or set the selection via DOM elements, use selectedItems. 

// Set a single value
listbox.value = 'a';

// Set multiple values
listbox.selectedValues = ['a', 'b', 'c'];

// Set using DOM elements
const itemA = document.querySelector('quiet-listbox-item#a');
const itemB = document.querySelector('quiet-listbox-item#b');
const itemC = document.querySelector('quiet-listbox-item#c');

listbox.selectedItems = [itemA, itemB, itemC];

Convenience methods Jump to heading

Use selectAll() and deselectAll() as a quick way to select all or no items.

// Select all items
listbox.selectAll();

// Deselect all items
listbox.deselectAll();

Disabling items Jump to heading

Add the disabled attribute to individual listbox items to make them non-selectable.

Morning (7am) Noon (12pm) Night (10pm) - Currently unavailable 
<quiet-listbox label="Feeding Schedule">
  <quiet-listbox-item value="morning">Morning (7am)</quiet-listbox-item>
  <quiet-listbox-item value="noon">Noon (12pm)</quiet-listbox-item>
  <quiet-listbox-item value="night" disabled>Night (10pm) - Currently unavailable</quiet-listbox-item>
</quiet-listbox>

Multiple selection Jump to heading

Use the multiple attribute to enable multi-selection mode. Users can select multiple items using or + click, + click for ranges, or to select all. For coarse pointers, such as touch, tapping an item will toggle the selection.

Midnight Zoomies Knocking Things Off Tables Ignoring Expensive Toys Sitting on Open Books Watching Birds Through Windows Following You to the Bathroom Demanding Pets Then Biting Sleeping in Weird Positions Hiding in Paper Bags Sudden Grooming Sessions 
<quiet-listbox label="Kitty Behavior" description="Select your cat's typical antics." multiple>
  <quiet-listbox-item value="1">Midnight Zoomies</quiet-listbox-item>
  <quiet-listbox-item value="2" selected>Knocking Things Off Tables</quiet-listbox-item>
  <quiet-listbox-item value="3" selected>Ignoring Expensive Toys</quiet-listbox-item>
  <quiet-listbox-item value="4">Sitting on Open Books</quiet-listbox-item>
  <quiet-listbox-item value="5">Watching Birds Through Windows</quiet-listbox-item>
  <quiet-listbox-item value="6">Following You to the Bathroom</quiet-listbox-item>
  <quiet-listbox-item value="7" selected>Demanding Pets Then Biting</quiet-listbox-item>
  <quiet-listbox-item value="8">Sleeping in Weird Positions</quiet-listbox-item>
  <quiet-listbox-item value="9">Hiding in Paper Bags</quiet-listbox-item>
  <quiet-listbox-item value="10">Sudden Grooming Sessions</quiet-listbox-item>
</quiet-listbox>

Changing the size Jump to heading

Use the size attribute to change the listbox's size.

Cat Tree Food Bowl Scratching Post Toy Mouse 
<quiet-select label="Select a size" style="max-width: 18rem; margin-block-end: 2rem;">
  <option value="xs">Extra small</option>
  <option value="sm">Small</option>
  <option value="md">Medium</option>
  <option value="lg">Large</option>
  <option value="xl">Extra large</option>
</quiet-select>

<quiet-listbox 
  size="xs" 
  label="Cat Accessories"
  description="Size changes dynamically based on selection above"
  id="listbox__size"
  multiple
>
  <quiet-listbox-item value="cat-tree">Cat Tree</quiet-listbox-item>
  <quiet-listbox-item value="food-bowl">Food Bowl</quiet-listbox-item>
  <quiet-listbox-item value="scratching-post">Scratching Post</quiet-listbox-item>
  <quiet-listbox-item value="toy-mouse">Toy Mouse</quiet-listbox-item>
</quiet-listbox>

<script>
  const listbox = document.getElementById('listbox__size');
  const select = listbox.previousElementSibling;

  select.addEventListener('quiet-change', () => {
    listbox.size = select.value;
  });  
</script>

Disabling Jump to heading

Add the disabled attribute to disable the entire listbox.

Tuna Treats Chicken Bites Salmon Flakes Cheese Nibbles Catnip Crisps 
<quiet-listbox label="Treat Options" description="Treats temporarily unavailable." disabled>
  <quiet-listbox-item value="1">Tuna Treats</quiet-listbox-item>
  <quiet-listbox-item value="2" selected>Chicken Bites</quiet-listbox-item>
  <quiet-listbox-item value="3">Salmon Flakes</quiet-listbox-item>
  <quiet-listbox-item value="4">Cheese Nibbles</quiet-listbox-item>
  <quiet-listbox-item value="5">Catnip Crisps</quiet-listbox-item>
</quiet-listbox>

Showing labels on the side Jump to heading

With the quiet-side-label utility, you can show labels on the side instead of on top of the listbox. You can control the width of the label by setting the --label-width custom property.

Short-haired Long-haired Curly-coated
Green Blue Amber 
<quiet-listbox
  class="quiet-side-label"
  style="--label-width: 10ch;"
  name="fur" 
  label="Fur Type" 
  description="What's your cat's coat like?"
>
  <quiet-listbox-item value="short">Short-haired</quiet-listbox-item>
  <quiet-listbox-item value="long">Long-haired</quiet-listbox-item>
  <quiet-listbox-item value="curly">Curly-coated</quiet-listbox-item>
</quiet-listbox>
<br>
<quiet-listbox
  class="quiet-side-label"
  style="--label-width: 10ch;"
  name="eye" 
  label="Eye Color" 
  description="What color are your cat's eyes?"
>
  <quiet-listbox-item value="green">Green</quiet-listbox-item>
  <quiet-listbox-item value="blue">Blue</quiet-listbox-item>
  <quiet-listbox-item value="amber">Amber</quiet-listbox-item>
</quiet-listbox>

Validation Jump to heading

The required attribute can be used to enable validation using the Constraint Validation API .

Barely Audible Conversational Wake the Neighbors
Submit Reset 
<form action="about:blank" method="get" target="_blank">
  <quiet-listbox name="meow" label="Meow Volume" required>
    <quiet-listbox-item value="1">Barely Audible</quiet-listbox-item>
    <quiet-listbox-item value="2">Conversational</quiet-listbox-item>
    <quiet-listbox-item value="3">Wake the Neighbors</quiet-listbox-item>
  </quiet-listbox>
  <br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

Using custom validation Jump to heading

Use the setCustomValidity() method to make the listbox invalid and show a custom error message on submit. This will override all other validation parameters. To clear the error, call the method with an empty string.

Gentle Rumble Medium Motor Thunderous Vibration
Submit 
<form action="about:blank" method="get" target="_blank" id="listbox__custom-validation">
  <quiet-listbox 
    name="purr"
    label="Purr Intensity"
    description="This field will be invalid until custom validation is removed"
  >
    <quiet-listbox-item value="1">Gentle Rumble</quiet-listbox-item>
    <quiet-listbox-item value="2">Medium Motor</quiet-listbox-item>
    <quiet-listbox-item value="3">Thunderous Vibration</quiet-listbox-item>
  </quiet-listbox>
  <br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
</form>

<script type="module">
  import { allDefined } from '/dist/quiet.js';

  await allDefined();

  const form = document.getElementById('listbox__custom-validation');
  const listbox = form.querySelector('quiet-listbox');

  listbox.setCustomValidity('Not so fast, bubba!');
</script>

Styling validation Jump to heading

You can style valid and invalid listboxes using the :valid and :invalid pseudo classes.

Front Paws Only All Paws No Trimming Needed
Submit Reset 
<form action="about:blank" method="get" target="_blank" class="listbox__validation-pseudo">
  <quiet-listbox 
    name="claws"
    label="Claw Trimming"
    description="This field is required for grooming appointments"
    required
  >
    <quiet-listbox-item value="1">Front Paws Only</quiet-listbox-item>
    <quiet-listbox-item value="2">All Paws</quiet-listbox-item>
    <quiet-listbox-item value="3">No Trimming Needed</quiet-listbox-item>
  </quiet-listbox>
  <br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

<style>
  .listbox__validation-pseudo {
    quiet-listbox:valid {
      outline: solid 2px var(--quiet-constructive-stroke-mid);
      outline-offset: .5rem;
    }

    quiet-listbox:invalid {
      outline: solid 2px var(--quiet-destructive-stroke-mid);
      outline-offset: .5rem;
    }
  }
</style>

However, these selectors will match even before the user has had a chance to interact with the form. More often than not, you'll want to use the user-valid and user-invalid custom states instead. This way, validation styles are only shown after the user interacts with the form control or when the form is submitted.

Grain-Free Formula Senior Cat Diet Hairball Control
Submit Reset 
<form action="about:blank" method="get" target="_blank" class="listbox__validation-custom">
  <quiet-listbox 
    name="diet"
    label="Dietary Needs"
    description="Please select your cat's dietary preference"
    required
  >
    <quiet-listbox-item value="1">Grain-Free Formula</quiet-listbox-item>
    <quiet-listbox-item value="2">Senior Cat Diet</quiet-listbox-item>
    <quiet-listbox-item value="3">Hairball Control</quiet-listbox-item>
  </quiet-listbox>
  <br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

<style>
  .listbox__validation-custom {
    quiet-listbox:state(user-valid) {
      outline: solid 2px var(--quiet-constructive-stroke-mid);
      outline-offset: .5rem;
    }

    quiet-listbox:state(user-invalid) {
      outline: solid 2px var(--quiet-destructive-stroke-mid);
      outline-offset: .5rem;
    }
  }
</style>

Styling listboxes Jump to heading

Listboxes are styled like form controls for consistency, but feel free to customize them to your liking. Here's an example you might see in an email client.

Sir Fluffington III

Captain Whiskers

Lady Purrlington

Meowy McGee

Chairman Meow

 
<quiet-listbox 
  label="Select a message to view" 
  class="quiet-vh-label" 
  id="listbox__styling"
>
  <quiet-listbox-item value="1000">
    <quiet-avatar image="https://images.unsplash.com/photo-1735820474275-dd0ff4f28d71?q=80&w=256&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D"></quiet-avatar>
    <h4 class="name">Sir Fluffington III</h4>
    <time class="time" datetime="2025-03-20T14:45">2:45 PM</time>
    <div class="summary" aria-hidden="true">Just knocked your favorite vase off the shelf. Not sorry.</div>
    <quiet-icon class="attachment" name="paperclip" label="1 attachment"></quiet-icon>
  </quiet-listbox-item>

  <quiet-listbox-item value="1001">
    <quiet-avatar image="https://images.unsplash.com/photo-1529778873920-4da4926a72c2?q=80&w=256&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D"></quiet-avatar>
    <h4 class="name">Captain Whiskers</h4>
    <time class="time" datetime="2025-03-20T13:37">1:37 PM</time>
    <div class="summary" aria-hidden="true">Require immediate attention. Food bowl is half empty. This is an emergency.</div>
    <quiet-icon class="attachment" name="flag" family="filled" label="Urgent!"></quiet-icon>
  </quiet-listbox-item>

  <quiet-listbox-item value="1002">
    <quiet-avatar image="https://images.unsplash.com/photo-1569591159212-b02ea8a9f239?q=80&w=256&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D"></quiet-avatar>
    <h4 class="name">Lady Purrlington</h4>
    <time class="time" datetime="2025-03-20T11:15">11:15 AM</time>
    <div class="summary" aria-hidden="true">Your lap is required for napping purposes at 3 PM sharp. Clear your schedule.</div>
  </quiet-listbox-item>
  
  <quiet-listbox-item value="1003">
    <quiet-avatar image="https://images.unsplash.com/photo-1672487209629-4d52e0c043d0?q=80&w=256&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D"></quiet-avatar>
    <h4 class="name">Meowy McGee</h4>
    <time class="time" datetime="2025-03-20T10:22">10:22 AM</time>
    <div class="summary" aria-hidden="true">Spotted a bird outside. Making weird chattering noises. Send help.</div>
    <quiet-icon class="attachment" name="paperclip" label="1 attachment"></quiet-icon>
  </quiet-listbox-item>
  
  <quiet-listbox-item value="1004">
    <quiet-avatar image="https://images.unsplash.com/photo-1579014868745-23e405c5605d?q=80&w=400&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D"></quiet-avatar>
    <h4 class="name">Chairman Meow</h4>
    <time class="time" datetime="2025-03-20T09:30">9:30 AM</time>
    <div class="summary" aria-hidden="true">Have claimed the new cardboard box. All other cats shall bow to my superiority.</div>
  </quiet-listbox-item>  
</quiet-listbox>

<style>
  #listbox__styling {
    max-width: 600px;
    font-family: system-ui, -apple-system, BlinkMacSystemFont, sans-serif;

    &::part(listbox) {
      height: auto;
      padding-block: 0;
    }
    
    quiet-listbox-item {
      display: grid;
      grid-template-areas: 
        "avatar name time"
        "avatar summary attachment";
      grid-template-columns: auto 1fr auto;
      grid-gap: 4px .75em;
      padding: .75em;
      border-bottom-color: var(--quiet-neutral-stroke-softer);
      align-items: center;
    }

    quiet-listbox-item:has(+ quiet-listbox-item:state(selected)),
    quiet-listbox-item:state(selected) {
      border-bottom-color: var(--quiet-neutral-stroke-soft);
    }

    &:state(focused) {
      quiet-listbox-item:has(+ quiet-listbox-item:state(selected)),
      quiet-listbox-item:state(selected) {
        border-bottom-color: var(--quiet-primary-stroke-soft);
      }
    }
    
    quiet-avatar {
      grid-area: avatar;
      margin-right: 0.25rem;
    }
    
    .name {
      grid-area: name;
      margin: 0;
      font-size: 0.9375rem;
      font-weight: var(--quiet-font-weight-semibold);
    }
    
    .time {
      grid-area: time;
      font-size: 0.875em;
      color: var(--quiet-text-muted);
      justify-self: end;
      font-style: normal;
    }
    
    .summary {
      grid-area: summary;
      color: var(--quiet-text-muted);
      font-size: 0.875rem;
      white-space: nowrap;
      overflow: hidden;
      text-overflow: ellipsis;
      margin: 0;
    }
    
    .attachment {
      grid-area: attachment;
      color: var(--quiet-text-muted);
      justify-self: end;
      font-size: 0.875rem;

      &[name="flag"] {
        color: crimson;
      }
    }

    quiet-listbox-item:state(selected) {
      .name,
      .time,
      .summary,
      .attachment {
        color: var(--quiet-primary-text-on-soft);
      }
    }
  }
</style>

Note the use of aria-hidden on summaries, which reduces verbosity when used with screen readers.

API Jump to heading

Importing Jump to heading

The autoloader is the recommended way to import components but, if you prefer to do it manually, the following code snippets will be helpful.

CDN npm

To manually import <quiet-listbox> from the CDN, use the following code.

import 'https://cdn.jsdelivr.net/npm/@quietui/quiet-browser@1.0.0/dist/components/listbox/listbox.js';

To manually import <quiet-listbox> from npm, use the following code.

import '@quietui/quiet/dist/components/listbox/listbox.js';

Slots Jump to heading

Listbox supports the following slots. Learn more about using slots

Name Description
(default) Listbox items to show in the listbox.
label The listbox's label. For plain-text labels, you can use the label attribute instead.
description The listbox's description. For plain-text descriptions, you can use the description attribute instead.

Properties Jump to heading

Listbox has the following properties that can be set with corresponding attributes. In many cases, the attribute's name is the same as the property's name. If an attribute is different, it will be displayed after the property. Learn more about attributes and properties

Property / Attribute Description Reflects Type Default
label The listbox's label. If you need to provide HTML in the label, use the label slot instead. string
description The listbox's description. If you need to provide HTML in the description, use the description slot instead. string
name The name of the listbox. This will be submitted with the form as a name/value pair. string
multiple Enables multiple selection mode. boolean false
disabled Disables the listbox. boolean false
readonly Makes the text field a read-only field. boolean false
size The text field's size. 'xs'
'sm'
'md'
'lg'
'xl' 		'md'
form The form to associate this control with. If omitted, the closest containing <form> will be used. The value of this attribute must be an ID of a form in the same document or shadow root. string
required Makes the listbox required. Form submission will not be allowed when this is set and the listbox is blank. boolean false
value The listbox's value. For multiple selection, this will be the value of the first selected item.
selectedValues Gets or sets the currently selected values as an array. This property provides a consistent way to access or modify the selection state regardless of whether the listbox is in single or multiple selection mode. In single selection mode, it returns an array with either zero or one value. In multiple selection mode, it returns an array of all selected values. When setting this property in single mode, the first value in the array (if any) becomes the selected value. In multiple mode, all values in the array become selected.
selectedItems Gets or sets an array of selected listbox items. QuietListboxItem[]

Methods Jump to heading

Listbox supports the following methods. You can obtain a reference to the element and call them like functions in JavaScript. Learn more about methods

Name Description Arguments
getSelectedValues() Returns an array of all selected values.
setSelectedValues() Sets the selected items by value(s) without triggering events. Works for both single and multiple selection modes. values: string<br>string[]
selectAll() Convenience method for selecting all items.
deselectAll() Convenience method for deselecting all items.
focus() Sets focus to the listbox.
blur() Removes focus from the listbox.
checkValidity() Checks if the form control has any restraints and whether it satisfies them. If invalid, false will be returned and the invalid event will be dispatched. If valid, true will be returned.
reportValidity() Checks if the form control has any restraints and whether it satisfies them. If invalid, false will be returned and the invalid event will be dispatched. In addition, the problem will be reported to the user. If valid, true will be returned.
setCustomValidity() Sets a custom validation message for the form control. If this message is not an empty string, then the form control is considered invalid and the specified message will be displayed to the user when reporting validity. Setting an empty string clears the custom validity state. message: string

Events Jump to heading

Listbox dispatches the following custom events. You can listen to them the same way was native events. Learn more about custom events

Name Description
input
change
quiet-blur Emitted when the list box loses focus. This event does not bubble.
quiet-change Emitted when the user commits changes to the list box's selection. In single select mode, it occurs when a change is made and the listbox loses focus. In multiselect mode, it occurs whenever an option is toggled even while the listbox has focus.
quiet-focus Emitted when the list box receives focus. This event does not bubble.
quiet-input Emitted when the list box's selection changes from user input.

CSS parts Jump to heading

Listbox exposes internal elements that can be styled with CSS using the selectors shown below. Learn more about CSS parts

Name Description CSS selector
label The element that contains the text field's label. ::part(label)
description The element that contains the text field's description. ::part(description)
listbox The internal listbox container that holds listbox items. ::part(listbox)

Custom States Jump to heading

Listbox has the following custom states. You can target them with CSS using the selectors shown below. Learn more about custom states

Name Description CSS selector
disabled Applied when the text field is disabled. :state(disabled)
blank Applied when the text field has a blank value. :state(blank)
focused Applied when the text field has focus. :state(focused)
user-valid Applied when the text field is valid and the user has sufficiently interacted with it. :state(user-valid)
user-invalid Applied when the text field is invalid and the user has sufficiently interacted with it. :state(user-invalid)

Dependencies Jump to heading

Listbox automatically imports the following elements. Sub-dependencies are also included in this list.

Search this website Toggle dark mode Get the code on GitHub Follow @quietui.org on Bluesky Follow @quiet_ui on X

    No results found