Combobox

<quiet-combobox>

stable

since 1.0

form control

This component is a form-associated custom element. It will submit its value when given a name and placed inside a <form>.

Allows users to select from a list of options with type-ahead search.

Comboboxes implement the ARIA APG combobox pattern for roles and keyboard navigation, with enhanced screen reader announcements via ARIA live regions for improved context while navigating options.

              
                Persian
                Siamese
                Tabby
                Ragdoll
                Bengal
                Sphynx
                Calico
                Russian Blue
              
            

<quiet-combobox
  label="Select a cat breed"
  description="Type to search or select from the list"
  placeholder="Search breeds"
  with-clear
>
  <quiet-combobox-item value="persian">Persian</quiet-combobox-item>
  <quiet-combobox-item value="siamese">Siamese</quiet-combobox-item>
  <quiet-combobox-item value="tabby">Tabby</quiet-combobox-item>
  <quiet-combobox-item value="ragdoll">Ragdoll</quiet-combobox-item>
  <quiet-combobox-item value="bengal">Bengal</quiet-combobox-item>
  <quiet-combobox-item value="sphynx">Sphynx</quiet-combobox-item>
  <quiet-combobox-item value="calico">Calico</quiet-combobox-item>
  <quiet-combobox-item value="russian">Russian Blue</quiet-combobox-item>
</quiet-combobox>

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 combobox. If you want to provide HTML, use the label and description slots instead.

Choose your purrfect companion Browse our available cats or schedule a visit.

Luna (Tabby, 2 years)

Milo (Orange, 1 year)

Bella (Calico, 3 years)

<quiet-combobox placeholder="Type to search">
  <span slot="label">Choose your <strong>purrfect</strong> companion</span>
  <span slot="description">
    Browse our available cats or <a href="https://example.com/" target="_blank">schedule a visit</a>.
  </span>
  <quiet-combobox-item value="luna">Luna (Tabby, 2 years)</quiet-combobox-item>
  <quiet-combobox-item value="milo">Milo (Orange, 1 year)</quiet-combobox-item>
  <quiet-combobox-item value="bella">Bella (Calico, 3 years)</quiet-combobox-item>
</quiet-combobox>

Providing options Jump to heading

Create combobox options by adding <quiet-combobox-item> elements inside the combobox. Each item should have a value attribute that will be submitted with the form. If no value is provided, the text content is used.

              
                Playful and Energetic
                Cuddly Lap Cat
                Independent Spirit
                Social Butterfly
                Curious Explorer
              
            

<quiet-combobox label="Cat personalities" placeholder="Search personalities">
  <quiet-combobox-item value="playful">Playful and Energetic</quiet-combobox-item>
  <quiet-combobox-item value="cuddly">Cuddly Lap Cat</quiet-combobox-item>
  <quiet-combobox-item value="independent">Independent Spirit</quiet-combobox-item>
  <quiet-combobox-item value="social">Social Butterfly</quiet-combobox-item>
  <quiet-combobox-item value="curious">Curious Explorer</quiet-combobox-item>
</quiet-combobox>

Combobox items can have structured content with icons and details.

              
                  Available Now
                  Ready for adoption
                
                  Adoption Pending
                  Application in review
                
                  Medical Hold
                  Recovering from treatment
                
                  Foster Only
                  Temporary care needed

<quiet-combobox label="Adoption status" placeholder="Filter by status" id="combobox__structured">
  <quiet-combobox-item value="available">
    <quiet-icon slot="icon" name="circle-check" variant="constructive"></quiet-icon>
    <span>Available Now</span>
    <span slot="details">Ready for adoption</span>
  </quiet-combobox-item>
  <quiet-combobox-item value="pending">
    <quiet-icon slot="icon" name="clock" variant="informative"></quiet-icon>
    <span>Adoption Pending</span>
    <span slot="details">Application in review</span>
  </quiet-combobox-item>
  <quiet-combobox-item value="medical">
    <quiet-icon slot="icon" name="heart" variant="critical"></quiet-icon>
    <span>Medical Hold</span>
    <span slot="details">Recovering from treatment</span>
  </quiet-combobox-item>
  <quiet-combobox-item value="foster">
    <quiet-icon slot="icon" name="home" variant="primary"></quiet-icon>
    <span>Foster Only</span>
    <span slot="details">Temporary care needed</span>
  </quiet-combobox-item>
</quiet-combobox>

<style>
  #combobox__structured {
    quiet-combobox-item {
      padding-block: 0.75rem;
    }
  }
</style>

Avoid placing interactive elements such as buttons and links inside the combobox 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 combobox item you want to select initially. When using multiple, you can apply selected to more than one option.

              
                Morning (6-9 AM)
                Noon (11 AM-1 PM)
                Evening (5-7 PM)
                Night (8-10 PM)

<quiet-combobox label="Preferred feeding time" placeholder="Select a time">
  <quiet-combobox-item value="morning">Morning (6-9 AM)</quiet-combobox-item>
  <quiet-combobox-item value="noon" selected>Noon (11 AM-1 PM)</quiet-combobox-item>
  <quiet-combobox-item value="evening">Evening (5-7 PM)</quiet-combobox-item>
  <quiet-combobox-item value="night">Night (8-10 PM)</quiet-combobox-item>
</quiet-combobox>

Getting and setting the value Jump to heading

The combobox's value can be accessed and modified through JavaScript. For single selection, use the value property. For multiple selection, value will be an array.

// Single selection
const combobox = document.querySelector('quiet-combobox');
console.log(combobox.value); // "persian"
combobox.value = 'siamese';

// Multiple selection
const multiCombobox = document.querySelector('quiet-combobox[multiple]');
console.log(multiCombobox.value); // ["persian", "siamese"]
multiCombobox.value = ['bengal', 'ragdoll'];

Adding a clear button Jump to heading

Add the with-clear attribute to show a clear button when the combobox has a value. This allows users to quickly clear their selection.

              
                Yes, I want treats!
                No treats needed
                Maybe later

<quiet-combobox 
  label="With clear button"
  placeholder="Select and then clear"
  with-clear
>
  <quiet-combobox-item value="yes" selected>Yes, I want treats!</quiet-combobox-item>
  <quiet-combobox-item value="no">No treats needed</quiet-combobox-item>
  <quiet-combobox-item value="maybe">Maybe later</quiet-combobox-item>
</quiet-combobox>

Multiple selection Jump to heading

Use the multiple attribute to enable multi-selection mode. Selected items appear as tags in the input area. Users can remove tags by clicking the × button or pressing Backspace.

              
                Purring
                Kneading (Making Biscuits)
                Chirping at Birds
                Head Bunting
                Slow Blinking
                Midnight Zoomies
                Bringing "Gifts"
                Teeth Chattering
              
            

<quiet-combobox
  label="Cat behaviors"
  description="Select all behaviors your cat exhibits"
  placeholder="Search behaviors"
  multiple
  with-clear
>
  <quiet-combobox-item value="purring" selected>Purring</quiet-combobox-item>
  <quiet-combobox-item value="kneading">Kneading (Making Biscuits)</quiet-combobox-item>
  <quiet-combobox-item value="chirping" selected>Chirping at Birds</quiet-combobox-item>
  <quiet-combobox-item value="head-bunting">Head Bunting</quiet-combobox-item>
  <quiet-combobox-item value="slow-blinking">Slow Blinking</quiet-combobox-item>
  <quiet-combobox-item value="zoomies">Midnight Zoomies</quiet-combobox-item>
  <quiet-combobox-item value="bringing-gifts">Bringing "Gifts"</quiet-combobox-item>
  <quiet-combobox-item value="chattering">Teeth Chattering</quiet-combobox-item>
</quiet-combobox>

In multiple mode, the dropdown stays open after selecting an item, allowing users to quickly select multiple options. Press Escape or click outside to close the dropdown.

Creating custom items Jump to heading

Add the allow-create attribute to let users create new items by typing text that doesn't match an existing option. An "Add" option appears at the top of the dropdown, and selecting it commits the item.

              
                Whiskers
                Mittens
                Shadow

<quiet-combobox
  label="Cat names"
  description="Select existing names or type to create new ones"
  placeholder="Search or add a name"
  allow-create
  with-clear
>
  <quiet-combobox-item value="Whiskers">Whiskers</quiet-combobox-item>
  <quiet-combobox-item value="Mittens">Mittens</quiet-combobox-item>
  <quiet-combobox-item value="Shadow">Shadow</quiet-combobox-item>
</quiet-combobox>

The allow-create attribute also works in multiple-select mode.

              
                Whiskers
                Mittens
                Shadow

<quiet-combobox
  label="Favorite cat"
  placeholder="Search or add a cat"
  multiple
  allow-create
  with-clear
>
  <quiet-combobox-item value="Whiskers">Whiskers</quiet-combobox-item>
  <quiet-combobox-item value="Mittens">Mittens</quiet-combobox-item>
  <quiet-combobox-item value="Shadow">Shadow</quiet-combobox-item>
</quiet-combobox>

When a new item is created, a quiet-create event is emitted with detail.value, detail.label, and detail.item properties. You can use this to persist new items to a server.

              
                Bug
                Feature

<quiet-combobox
  label="Tags"
  placeholder="Add tags"
  multiple
  allow-create
  with-clear
  id="combobox__create-event"
>
  <quiet-combobox-item value="bug">Bug</quiet-combobox-item>
  <quiet-combobox-item value="feature">Feature</quiet-combobox-item>
</quiet-combobox>

<script>
  const combobox = document.getElementById('combobox__create-event');

  combobox.addEventListener('quiet-create', event => {
    console.log('Created:', event.detail.value, event.detail.label);
  });
</script>

You can customize the "Add" label and the value assigned to created items by overriding the getCustomLabel() and getCustomValue() methods.

const combobox = document.querySelector('quiet-combobox');

// Customize the dropdown label
combobox.getCustomLabel = (query) => `Create tag "${query}"`;

// Customize how values are generated
combobox.getCustomValue = (query) => query.trim().toLowerCase().replace(/\s+/g, '-');

Start and end content Jump to heading

Use the start and end slots to add presentational icons or text. Avoid interactive elements such as buttons, links, etc. Works well with <quiet-icon> and <svg> elements.

              
                Persian
                Siamese
                Tabby
                Ragdoll
              
                Feather Wand
                Laser Pointer
                Catnip Mouse
                Puzzle Feeder
              
                Annual Checkup
                Vaccination
                Dental Cleaning
                Grooming

<quiet-combobox name="breed" label="Cat breed" with-clear>
  <quiet-icon slot="start" name="cat"></quiet-icon>
  <quiet-combobox-item value="persian">Persian</quiet-combobox-item>
  <quiet-combobox-item value="siamese">Siamese</quiet-combobox-item>
  <quiet-combobox-item value="tabby">Tabby</quiet-combobox-item>
  <quiet-combobox-item value="ragdoll">Ragdoll</quiet-combobox-item>
</quiet-combobox>

<br>

<quiet-combobox name="toy" label="Cat toy" placeholder="Choose a toy" with-clear>
  <quiet-icon slot="end" name="gift"></quiet-icon>
  <quiet-combobox-item value="feather-wand">Feather Wand</quiet-combobox-item>
  <quiet-combobox-item value="laser-pointer">Laser Pointer</quiet-combobox-item>
  <quiet-combobox-item value="catnip-mouse">Catnip Mouse</quiet-combobox-item>
  <quiet-combobox-item value="puzzle-feeder">Puzzle Feeder</quiet-combobox-item>
</quiet-combobox>

<br>

<quiet-combobox name="vet-visit" label="Visit type" multiple with-clear>
  <quiet-icon slot="start" name="cat"></quiet-icon>
  <quiet-icon slot="end" name="clipboard-heart"></quiet-icon>
  <quiet-combobox-item value="checkup">Annual Checkup</quiet-combobox-item>
  <quiet-combobox-item value="vaccination">Vaccination</quiet-combobox-item>
  <quiet-combobox-item value="dental">Dental Cleaning</quiet-combobox-item>
  <quiet-combobox-item value="grooming">Grooming</quiet-combobox-item>
</quiet-combobox>

Filled and unstyled comboboxes Jump to heading

Use the appearance attribute to change the visual style of the combobox. Options are normal (default), filled, and unstyled.

              
                Fluffy
                Sleek
                Short-haired
              
                Fluffy
                Sleek
                Short-haired
              
                Fluffy
                Sleek
                Short-haired

<quiet-combobox 
  label="Normal appearance"
  appearance="normal"
  placeholder="Select one"
>
  <quiet-combobox-item value="1">Fluffy</quiet-combobox-item>
  <quiet-combobox-item value="2">Sleek</quiet-combobox-item>
  <quiet-combobox-item value="3">Short-haired</quiet-combobox-item>
</quiet-combobox>

<br>

<quiet-combobox 
  label="Filled appearance"
  appearance="filled"
  placeholder="Select one"
>
  <quiet-combobox-item value="1">Fluffy</quiet-combobox-item>
  <quiet-combobox-item value="2">Sleek</quiet-combobox-item>
  <quiet-combobox-item value="3">Short-haired</quiet-combobox-item>
</quiet-combobox>

<br>

<quiet-combobox 
  label="Unstyled appearance"
  appearance="unstyled"
  placeholder="Select one"
>
  <quiet-combobox-item value="1">Fluffy</quiet-combobox-item>
  <quiet-combobox-item value="2">Sleek</quiet-combobox-item>
  <quiet-combobox-item value="3">Short-haired</quiet-combobox-item>
</quiet-combobox>

Pill-shaped comboboxes Jump to heading

Add the pill attribute to give the combobox rounded edges.

              
                Salmon Bites
                Chicken Strips
                Tuna Flakes
                Catnip Cookies
                Cheese Cubes
              
            

<quiet-combobox 
  label="Cat's favorite treat"
  placeholder="Choose a treat"
  pill
  with-clear
>
  <quiet-combobox-item value="salmon">Salmon Bites</quiet-combobox-item>
  <quiet-combobox-item value="chicken">Chicken Strips</quiet-combobox-item>
  <quiet-combobox-item value="tuna">Tuna Flakes</quiet-combobox-item>
  <quiet-combobox-item value="catnip">Catnip Cookies</quiet-combobox-item>
  <quiet-combobox-item value="cheese">Cheese Cubes</quiet-combobox-item>
</quiet-combobox>

When using multiple, tags become pill-shaped and the combobox will curve to wrap around them.

              
                Bird Watching
                Sunbathing
                Toy Hunting
                Box Sitting
                Treat Begging
                Midnight Racing
                Lap Napping
              
            

<quiet-combobox 
  label="Cat's daily activities"
  description="Select all that apply"
  placeholder="What does your cat enjoy?"
  pill
  multiple
  with-clear
>
  <quiet-combobox-item value="window-watching" selected>Bird Watching</quiet-combobox-item>
  <quiet-combobox-item value="sunbathing" selected>Sunbathing</quiet-combobox-item>
  <quiet-combobox-item value="toy-hunting" selected>Toy Hunting</quiet-combobox-item>
  <quiet-combobox-item value="box-sitting" selected>Box Sitting</quiet-combobox-item>
  <quiet-combobox-item value="treat-begging" selected>Treat Begging</quiet-combobox-item>
  <quiet-combobox-item value="midnight-racing" selected>Midnight Racing</quiet-combobox-item>
  <quiet-combobox-item value="lap-napping" selected>Lap Napping</quiet-combobox-item>
</quiet-combobox>

Changing the size Jump to heading

Use the size attribute to change the combobox's size. Available sizes are xs, sm, md (default), lg, and xl.

              
                Extra small
                Small
                Medium
                Large
                Extra large
              
                Solid Color
                Tabby Stripes
                Calico
                Tortoiseshell
                Tuxedo
                Pointed (Siamese)

<quiet-select label="Select a size" value="xs" 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-combobox 
  size="xs" 
  label="Cat coat pattern"
  description="Size changes dynamically based on selection above"
  placeholder="Search patterns"
  id="combobox__size"
  with-clear
>
  <quiet-combobox-item value="solid">Solid Color</quiet-combobox-item>
  <quiet-combobox-item value="tabby">Tabby Stripes</quiet-combobox-item>
  <quiet-combobox-item value="calico">Calico</quiet-combobox-item>
  <quiet-combobox-item value="tortoiseshell">Tortoiseshell</quiet-combobox-item>
  <quiet-combobox-item value="tuxedo">Tuxedo</quiet-combobox-item>
  <quiet-combobox-item value="pointed">Pointed (Siamese)</quiet-combobox-item>
</quiet-combobox>

<script>
  const combobox = document.getElementById('combobox__size');
  const select = combobox.previousElementSibling;

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

Disabling the combobox Jump to heading

Add the disabled attribute to disable the entire combobox.

              
                Bath & Blow-dry
                Nail Trim
                Full Grooming

<quiet-combobox 
  label="Grooming services" 
  description="Currently unavailable"
  placeholder="Service selection disabled"
  disabled
>
  <quiet-combobox-item value="bath">Bath & Blow-dry</quiet-combobox-item>
  <quiet-combobox-item value="trim" selected>Nail Trim</quiet-combobox-item>
  <quiet-combobox-item value="full">Full Grooming</quiet-combobox-item>
</quiet-combobox>

Disabling items Jump to heading

Add the disabled attribute to individual combobox items to make them non-selectable. Disabled items will still appear in search results but cannot be selected.

              
                Annual Checkup
                Vaccination
                Spay/Neuter (Fully booked)
                Dental Cleaning
                Emergency Care (Call first)
              
            

<quiet-combobox label="Veterinary services" placeholder="Select service">
  <quiet-combobox-item value="checkup">Annual Checkup</quiet-combobox-item>
  <quiet-combobox-item value="vaccination">Vaccination</quiet-combobox-item>
  <quiet-combobox-item value="spay-neuter" disabled>Spay/Neuter (Fully booked)</quiet-combobox-item>
  <quiet-combobox-item value="dental">Dental Cleaning</quiet-combobox-item>
  <quiet-combobox-item value="emergency" disabled>Emergency Care (Call first)</quiet-combobox-item>
</quiet-combobox>

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 combobox. You can control the width of the label by setting the --label-width custom property.

              
                Kitten (0-1 year)
                Young (1-3 years)
                Adult (3-7 years)
                Senior (7+ years)
              
                Couch Potato
                Moderately Active
                Very Energetic

<quiet-combobox
  class="quiet-side-label"
  style="--label-width: 12ch;"
  name="age" 
  label="Cat's age" 
  description="How old is your cat?"
  placeholder="Select age range"
>
  <quiet-combobox-item value="kitten">Kitten (0-1 year)</quiet-combobox-item>
  <quiet-combobox-item value="young">Young (1-3 years)</quiet-combobox-item>
  <quiet-combobox-item value="adult">Adult (3-7 years)</quiet-combobox-item>
  <quiet-combobox-item value="senior">Senior (7+ years)</quiet-combobox-item>
</quiet-combobox>
<br>
<quiet-combobox
  class="quiet-side-label"
  style="--label-width: 12ch;"
  name="activity" 
  label="Activity level" 
  description="How active is your cat?"
  placeholder="Select activity"
>
  <quiet-combobox-item value="low">Couch Potato</quiet-combobox-item>
  <quiet-combobox-item value="moderate">Moderately Active</quiet-combobox-item>
  <quiet-combobox-item value="high">Very Energetic</quiet-combobox-item>
</quiet-combobox>

Validation Jump to heading

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

              
                  Dr. Smith - City Animal Hospital
                  Dr. Jones - Pet Emergency Center
                  Dr. Brown - 24/7 Pet Care
                
                Submit
                Reset

<form action="about:blank" method="get" target="_blank">
  <quiet-combobox 
    name="emergency-contact" 
    label="Emergency vet contact" 
    placeholder="Select a veterinarian"
    required
  >
    <quiet-combobox-item value="dr-smith">Dr. Smith - City Animal Hospital</quiet-combobox-item>
    <quiet-combobox-item value="dr-jones">Dr. Jones - Pet Emergency Center</quiet-combobox-item>
    <quiet-combobox-item value="dr-brown">Dr. Brown - 24/7 Pet Care</quiet-combobox-item>
  </quiet-combobox>
  <br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

Min and max validation Jump to heading

In multiple mode, use the min and max attributes to validate the number of selections. The max attribute also prevents selecting beyond the limit. These attributes are ignored in single-select mode.

              
                  Purring
                  Kneading
                  Chirping at Birds
                  Head Bunting
                  Slow Blinking
                  Midnight Zoomies
                
                Submit
                Reset

<form action="about:blank" method="get" target="_blank">
  <quiet-combobox
    name="behaviors"
    label="Cat behaviors"
    description="Select between 2 and 4 behaviors"
    placeholder="Search behaviors"
    multiple
    min="2"
    max="4"
    with-clear
  >
    <quiet-combobox-item value="purring">Purring</quiet-combobox-item>
    <quiet-combobox-item value="kneading">Kneading</quiet-combobox-item>
    <quiet-combobox-item value="chirping">Chirping at Birds</quiet-combobox-item>
    <quiet-combobox-item value="head-bunting">Head Bunting</quiet-combobox-item>
    <quiet-combobox-item value="slow-blinking">Slow Blinking</quiet-combobox-item>
    <quiet-combobox-item value="zoomies">Midnight Zoomies</quiet-combobox-item>
  </quiet-combobox>
  <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 combobox 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.

              
                  Regular Diet
                  Grain-Free
                  Prescription Diet
                
                Submit

<form action="about:blank" method="get" target="_blank" id="combobox__custom-validation">
  <quiet-combobox 
    name="special-diet"
    label="Special dietary needs"
    description="This field demonstrates custom validation"
    placeholder="Select diet"
  >
    <quiet-combobox-item value="regular">Regular Diet</quiet-combobox-item>
    <quiet-combobox-item value="grain-free">Grain-Free</quiet-combobox-item>
    <quiet-combobox-item value="prescription">Prescription Diet</quiet-combobox-item>
  </quiet-combobox>
  <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('combobox__custom-validation');
  const combobox = form.querySelector('quiet-combobox');

  combobox.setCustomValidity('Please consult with your vet first!');
  
  // Clear validation after user selects an option
  combobox.addEventListener('quiet-change', () => {
    combobox.setCustomValidity('');
  });
</script>

Styling validation Jump to heading

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

<form action="about:blank" method="get" target="_blank" class="combobox__validation-pseudo">
  <quiet-combobox 
    name="chip-id"
    label="Microchip ID"
    description="Required for registration"
    placeholder="Enter or select chip ID"
    required
  >
    <quiet-combobox-item value="chip-12345">CHIP-12345</quiet-combobox-item>
    <quiet-combobox-item value="chip-67890">CHIP-67890</quiet-combobox-item>
    <quiet-combobox-item value="chip-24680">CHIP-24680</quiet-combobox-item>
  </quiet-combobox>
  <br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

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

    quiet-combobox: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.

              
                  PawGuard Plus
                  Furry Shield
                  PetCare Prime
                  Whiskers Wellness
                
                Submit
                Reset

<form action="about:blank" method="get" target="_blank" class="combobox__validation-custom">
  <quiet-combobox 
    name="insurance"
    label="Pet insurance provider"
    description="Select your insurance company"
    placeholder="Search providers"
    required
  >
    <quiet-combobox-item value="pawguard-plus">PawGuard Plus</quiet-combobox-item>
    <quiet-combobox-item value="furry-shield">Furry Shield</quiet-combobox-item>
    <quiet-combobox-item value="petcare-prime">PetCare Prime</quiet-combobox-item>
    <quiet-combobox-item value="whiskers-wellness">Whiskers Wellness</quiet-combobox-item>
  </quiet-combobox>
  <br>
  <quiet-button type="submit" variant="primary">Submit</quiet-button>
  <quiet-button type="reset">Reset</quiet-button>
</form>

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

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

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

Self-hosted

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

import 'https://cdn.quietui.org/v5.0.0/components/combobox/combobox.js';

To manually import <quiet-combobox> from a self-hosted distribution, use the following code. Remember to replace /path/to/quiet with the appropriate local path.

import '/path/to/quiet/components/combobox/combobox.js';

Slots Jump to heading

Combobox supports the following slots. Learn more about using slots

Name	Description
(default)	One or more `<quiet-combobox-item>` elements to show as options.
`label`	The combobox's label. For plain-text labels, use the `label` attribute instead.
`description`	The combobox's description. For plain-text descriptions, use the `description` attribute instead.
`start`	An icon or similar element to place before the input. Works great with `<quiet-icon>`.
`end`	An icon or similar element to place after the input. Works great with `<quiet-icon>`.

Properties Jump to heading

Combobox 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	Description	Type	Default
`query`	The current text in the combobox's search box. Useful for reading when handling `quiet-input` events.	`string`	`''`
`label`	The combobox's label.	`string`
`description`	The combobox's description.	`string`
`name`	The name of the combobox for form submission.	`string`
`value`	The combobox's value(s).	`string string[]`	`''`
`placeholder`	Placeholder text for the input.	`string`
`disabled`	Disables the combobox.	`boolean`	`false`
`required`	Makes the combobox required.	`boolean`	`false`
`multiple`	Enables multiple selection.	`boolean`	`false`
`withClear` `with-clear`	Adds a clear button when not blank.	`boolean`	`false`
`appearance`	The visual appearance of the combobox.	`'normal' 'filled' 'unstyled'`	`'normal'`
`size`	The size of the combobox.	`'xs' 'sm' 'md' 'lg' 'xl'`	`'md'`
`pill`	Draws the combobox in a pill shape.	`boolean`	`false`
`placement`	The dropdown's placement relative to the input.	`'top' 'top-start' 'top-end' 'bottom' 'bottom-start' 'bottom-end'`	`'bottom-start'`
`distance`	The distance of the dropdown from the input.	`number`	`0`
`offset`	The offset of the dropdown along the input.	`number`	`0`
`min`	The minimum number of selections required for validation in multiple mode. Set to 0 for no minimum.	`number`	`0`
`max`	The maximum number of selections allowed in multiple mode. Set to 0 for no limit. When the limit is reached, no more selections can be made.	`number`	`0`
`allowCreate` `allow-create`	Allows users to create new items by typing text that doesn't match an existing option.	`boolean`	`false`
`form`	The form to associate with.	`string`
`inputmode`	Provides the browser with a hint about the type of data that might be entered by the user, allowing the appropriate virtual keyboard to be displayed on supported devices.	`'none' 'text' 'decimal' 'numeric' 'tel' 'search' 'email' 'url'`
`autocapitalize`	Turns autocapitalize on or off in supported browsers.	`'off' 'none' 'on' 'sentences' 'words' 'characters'`
`autocorrect`	Turns autocorrect on or off in supported browsers.	`boolean`
`enterkeyhint`	Sets the enter key label on virtual keyboards.	`'enter' 'done' 'go' 'next' 'previous' 'search' 'send'`
`spellcheck`	Turns spell checking on or off in supported browsers.	`boolean`

Methods Jump to heading

Combobox 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
`getTagContent()`	A custom function for rendering tag content. By default, this function returns the item's full `textContent`. You can override it to customize the content that gets rendered in tags in `multiple` mode.	`item: QuietComboboxItem`
`focus()`	Sets focus to the combobox.
`blur()`	Removes focus from the combobox.
`getCustomLabel()`	Returns the label shown for the "Add" option when `allow-create` is enabled. Override this method to customize the display text. By default, returns a localized string like `Add "query"`.	`query: string`
`getCustomValue()`	Returns the value assigned to a newly created item when `allow-create` is enabled. Override this method to customize how the query text is transformed into a value. By default, returns the trimmed query text.	`query: string`
`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

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

Name	Description
`quiet-blur`	Emitted when the combobox loses focus.
`quiet-change`	Emitted when the user commits changes to the combobox's value.
`quiet-focus`	Emitted when the combobox receives focus.
`quiet-input`	Emitted when the combobox receives input.
`quiet-before-open`	Emitted when the dropdown is instructed to open but before it is shown.
`quiet-open`	Emitted when the dropdown opens.
`quiet-before-close`	Emitted when the dropdown is instructed to close but before it is hidden.
`quiet-close`	Emitted when the dropdown closes.
`quiet-create`	Emitted when a new item is created via the `allow-create` feature. The event `detail` contains `value`, `label`, and `item` properties.

CSS custom properties Jump to heading

Combobox supports the following CSS custom properties. You can style them like any other CSS property. Learn more about CSS custom properties

Name	Description	Default
`--text-box-min-width`	The minimum width of the input field when shown next to tags. Only available in `multiple` mode.	`12ch`
`--show-duration`	The duration of the show/hide animation for the dropdown.	`50ms`

CSS parts Jump to heading

Combobox 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 combobox's label.	`::part(label)`
`description`	The element that contains the combobox's description.	`::part(description)`
`visual-box`	The element that wraps the internal text box.	`::part(visual-box)`
`input-area`	The wrapper surrounding tags and the internal text box.	`::part(input-area)`
`tag`	Individual tag elements.	`::part(tag)`
`tag-label`	The text label inside a tag.	`::part(tag-label)`
`tag-remove`	The remove button for tags.	`::part(tag-remove)`
`text-box`	The internal text box, an `<input>` element.	`::part(text-box)`
`chevron`	The chevron icon, a `<quiet-icon>` element.	`::part(chevron)`
`chevron__svg`	The chevron icon's `<svg>` part.	`::part(chevron__svg)`
`clear-button`	The clear button.	`::part(clear-button)`
`dropdown`	The dropdown container.	`::part(dropdown)`

Custom States Jump to heading

Combobox 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
`open`	Applied when the dropdown is open.	`:state(open)`
`disabled`	Applied when the combobox is disabled.	`:state(disabled)`
`focused`	Applied when the combobox has focus.	`:state(focused)`
`blank`	Applied when the combobox has no value.	`:state(blank)`
`user-valid`	Applied when valid after user interaction.	`:state(user-valid)`
`user-invalid`	Applied when invalid after user interaction.	`:state(user-invalid)`

Dependencies Jump to heading

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

Combobox

Examples Jump to heading #

Labels and descriptions Jump to heading #

Providing options Jump to heading #

Providing an initial value Jump to heading #

Getting and setting the value Jump to heading #

Adding a clear button Jump to heading #

Multiple selection Jump to heading #

Creating custom items Jump to heading #

Start and end content Jump to heading #

Filled and unstyled comboboxes Jump to heading #

Pill-shaped comboboxes Jump to heading #

Changing the size Jump to heading #

Disabling the combobox Jump to heading #

Disabling items Jump to heading #

Showing labels on the side Jump to heading #

Validation Jump to heading #

Min and max validation Jump to heading #

Using custom validation Jump to heading #

Styling validation Jump to heading #

API Jump to heading #

Importing Jump to heading #

Slots Jump to heading #

Properties Jump to heading #

Methods Jump to heading #

Events Jump to heading #

CSS custom properties Jump to heading #

CSS parts Jump to heading #

Custom States Jump to heading #

Dependencies Jump to heading #