a-list

The a-list element provides an accessible list with keyboard navigation and selection support. It's useful for building custom select dropdowns, menu lists, and any interface where users need to choose from a list of options.

Preselected value

Usage

Basic List

<a-list>
  <a-list-item value="apple">Apple</a-list-item>
  <a-list-item value="banana">Banana</a-list-item>
  <a-list-item value="orange">Orange</a-list-item>
</a-list>

With Initial Selection

<a-list value="banana">
  <a-list-item value="apple">Apple</a-list-item>
  <a-list-item value="banana">Banana</a-list-item>
  <a-list-item value="orange">Orange</a-list-item>
</a-list>

Listening for Selection

const list = document.querySelector('a-list');

list.addEventListener('change', (event) => {
  console.log('Selected:', event.target.value);
  console.log('Selected item:', event.detail.selected);
});

list.addEventListener('input', (event) => {
  // Fired when focus moves between items
  console.log('Focused:', event.detail);
});

Programmatic Selection

const list = document.querySelector('a-list');

// Set selection by value
list.value = 'orange';

// Navigate programmatically
list.selectNext();
list.selectPrev();

Keyboard Navigation

Key	Action
ArrowDown	Move to next item
ArrowUp	Move to previous item
Enter	Confirm selection
Home	Move to first item
End	Move to last item
Type character	Jump to item starting with that letter

Accessibility

• Role: The list has role="listbox" and items have role="option".
• ARIA Selection: Items have aria-selected to indicate selection state.
• Focus Management: The list is focusable and manages focus between items.
• Keyboard Support: Full keyboard navigation as described above.
  • Keyboard navigation (Arrow keys, Home, End)
  • Type-ahead character search
  • Single selection with visual feedback
  • Scroll-into-view for selected items

<label id="fruit-label">Choose a fruit</label>
<a-list aria-labelledby="fruit-label">
  <a-list-item value="apple">Apple</a-list-item>
  <a-list-item value="banana">Banana</a-list-item>
</a-list>

Styling

a-list {
  display: flex;
  flex-direction: column;
  max-height: 300px;
  overflow-y: auto;
}

a-list-item {
  padding: 0.75rem 1rem;
  cursor: pointer;
}

a-list-item:hover {
  background-color: #f3f4f6;
}

a-list-item[aria-selected="true"] {
  background-color: #e5e7eb;
}

API Reference

References

• WAI-ARIA Listbox Pattern
• MDN: ARIA listbox role