ul
The unordered list element represents a collection of items where the sequence does not matter.
Description
The <ul> element creates a bulleted list of items. Each item is wrapped in an <li> element. Use unordered lists when the order of items is not meaningful or does not affect the content's meaning.
By default, items are displayed with disc-style bullet markers and left padding for indentation.
When to Use
- Feature lists or bullet points
- Navigation menus (wrap in
<nav>) - Collections of links or resources
- Tag or category listings
- Metadata lines (
.metavariant) - Any group where sequence does not matter
When Not to Use
Default
Standard unordered list with bullet markers.
<ul> <li>First item in the list</li> <li>Second item in the list</li> <li>Third item in the list</li> <li>Fourth item in the list</li></ul>Variants
.inline
Display list items horizontally using flexbox. Removes bullets and arranges items in a row with gap spacing.
.unstyled
Remove bullets and indentation for custom styling or navigation menus.
<ul class="inline"> <li>Home</li> <li>About</li> <li>Services</li> <li>Contact</li></ul><ul class="unstyled"> <li>No bullets here</li> <li>Just plain text</li> <li>Useful for navigation</li> <li>Or custom layouts</li></ul>Custom Markers
Use the data-marker attribute to replace default bullets with character tokens. Available markers: check, arrow, dash, and star.
<ul data-marker="check"> <li>Task completed</li> <li>Another done item</li></ul> <ul data-marker="arrow"> <li>Navigate here</li> <li>Go to settings</li></ul> <ul data-marker="dash"> <li>Minimal style</li></ul> <ul data-marker="star"> <li>Featured item</li></ul>| Attribute Value | Marker | Color |
|---|---|---|
data-marker="check" |
✔ (check mark) | --color-success |
data-marker="arrow" |
➤ (arrow) | --color-interactive |
data-marker="dash" |
⁃ (dash) | currentColor |
data-marker="star" |
★ (star) | --color-interactive |
Metadata List
The .meta class creates an inline list with separator characters between items. Ideal for article bylines, breadcrumbs, or tag displays.
<ul class="meta"> <li>Jane Smith</li> <li><time datetime="2024-01-15">Jan 15, 2024</time></li> <li>5 min read</li></ul> <!-- Separator variants --><ul class="meta" data-separator="pipe">...</ul><ul class="meta" data-separator="dash">...</ul><ul class="meta" data-separator="slash">...</ul>| Attribute | Separator |
|---|---|
| (default) | · (middle dot) |
data-separator="pipe" |
| (pipe) |
data-separator="dash" |
– (en dash) |
data-separator="slash" |
/ (slash) |
Nested Lists
Lists can be nested to create hierarchical structures. Nested lists automatically change their bullet style at each level.
<ul> <li>Fruits <ul> <li>Apples</li> <li>Oranges</li> <li>Bananas</li> </ul> </li> <li>Vegetables <ul> <li>Carrots</li> <li>Broccoli</li> </ul> </li> <li>Grains</li></ul>Navigation Usage
Unordered lists are commonly used for navigation menus. Wrap the list in a <nav> element for proper semantics.
<nav aria-label="Example navigation"> <ul class="unstyled"> <li><a href="#">Home</a></li> <li><a href="#">Products</a></li> <li><a href="#">About Us</a></li> <li><a href="#">Contact</a></li> </ul></nav>Accessibility
Screen Reader Behavior
- Announced as "list" with item count (e.g., "list, 4 items")
- Each item announced as "list item" with position
- Nested lists are announced with their own item counts
Best Practices
- Use semantic list markup instead of styled elements for list content
- Do not remove list semantics with
role="presentation"unless intentional - For navigation, wrap in
<nav>witharia-label - Avoid deeply nested lists (3+ levels) as they become hard to navigate
Safari / VoiceOver
The .unstyled class removes visual bullets but preserves list semantics. In Safari/VoiceOver, list-style: none may remove list semantics. To preserve them explicitly:
<ul class="unstyled" role="list"> <li>Item with explicit list role</li></ul>CSS Properties
| Property | Value | Description |
|---|---|---|
padding-inline-start |
var(--size-l) |
Left indentation for list items |
Variant: .inline
| Property | Value |
|---|---|
display |
flex |
flex-wrap |
wrap |
gap |
var(--size-s) |
list-style |
none |
Variant: .unstyled
| Property | Value |
|---|---|
padding-inline-start |
0 |
list-style |
none |