List

Component status:Ready

A List vertically organizes related content.

Examples

Unordered List

• List item 1
  • List item 1A
  • List item 1B
• List item 2
• List item 3
  • List item 3A
    • List item 3Ai
    • List item 3Aii
  • List item 3B

<ul class="bux-list-ul">
  <li>
    List item 1
    <ul>
      <li>List item 1A</li>
      <li>List item 1B</li>
    </ul>
  </li>
  <li>List item 2</li>
  <li>
    List item 3
    <ul>
      <li>
        List item 3A
        <ul>
          <li>List item 3Ai</li>
          <li>List item 3Aii</li>
        </ul>
      </li>
      <li>List item 3B</li>
    </ul>
  </li>
</ul>

{#
Buckeye UX - version 1.1.0
Copyright (C) 2025 The Ohio State University
#}

<ul class='bux-list-ul'>
	{% for item in list_items %}
		{% if item.level2_items %}
			<li>
				{{- item.text -}}
				<ul>
					{% for item in item.level2_items %}
						{% if item.level3_items %}
							<li>
								{{- item.text -}}
								<ul>
									{% for item in item.level3_items %}
										<li>{{- item.text -}}</li>
									{% endfor %}
								</ul>
							</li>
						{% else %}
							<li>{{- item.text -}}</li>
						{% endif %}
					{% endfor %}
				</ul>
			</li>
		{% else %}
			<li>{{- item.text -}}</li>
		{% endif %}
	{% endfor %}
</ul>

Ordered List

1. List item 1
   1. List item 1A
   2. List item 1B
2. List item 2
3. List item 3
   1. List item 3A
      1. List item 3Ai
      2. List item 3Aii
   2. List item 3B

<ol class="bux-list-ol">
  <li>
    List item 1
    <ol>
      <li>List item 1A</li>
      <li>List item 1B</li>
    </ol>
  </li>
  <li>List item 2</li>
  <li>
    List item 3
    <ol>
      <li>
        List item 3A
        <ol>
          <li>List item 3Ai</li>
          <li>List item 3Aii</li>
        </ol>
      </li>
      <li>List item 3B</li>
    </ol>
  </li>
</ol>

{#
Buckeye UX - version 1.1.0
Copyright (C) 2025 The Ohio State University
#}

<ol class="bux-list-ol">
	{% for item in list_items %}
		{% if item.level2_items %}
			<li>
				{{- item.text -}}
				<ol>
					{% for item in item.level2_items %}
						{% if item.level3_items %}
							<li>
								{{- item.text -}}
								<ol>
									{% for item in item.level3_items %}
										<li>{{- item.text -}}</li>
									{% endfor %}
								</ol>
							</li>
						{% else %}
							<li>{{- item.text -}}</li>
						{% endif %}
					{% endfor %}
				</ol>
			</li>
		{% else %}
			<li>{{- item.text -}}</li>
		{% endif %}
	{% endfor %}
</ol>

Description List

Term 1

This is the definition of the first term.

Term 2

This is the definition of the second term.

Term 3

This is the definition of the third term.

<dl class="bux-dl">
  <dt>Term 1</dt>
  <dd>This is the definition of the first term.</dd>
  <dt>Term 2</dt>
  <dd>This is the definition of the second term.</dd>
  <dt>Term 3</dt>
  <dd>This is the definition of the third term.</dd>
</dl>

{#
Buckeye UX - version 1.1.0
Copyright (C) 2025 The Ohio State University
#}

<dl class="bux-dl">
	{% for item in list_items %}
		<dt>{{ item.term }}</dt>
		<dd>{{ item.desc }}</dd>
	{% endfor %}
</dl>

Description List with Icon

Email

lastname.123@osu.edu

Phone

614-555-5555

Office

4088 Postle Hall, 305 W. 12th Avenue, Columbus, OH 43210

Links

A Day in the Life: Ken's blog

<dl class="bux-icon-dl">
  <div class="bux-icon-dl__item">
    <dt class="icon icon-envelope">Email</dt>
    <dd>
      <a class="bux-link" href="mailto:lastname.123@osu.edu"
        >lastname.123@osu.edu</a
      >
    </dd>
  </div>
  <div class="bux-icon-dl__item">
    <dt class="icon icon-phone">Phone</dt>
    <dd>
      <a class="bux-link" href="tel:614-555-5555">614-555-5555</a>
    </dd>
  </div>
  <div class="bux-icon-dl__item">
    <dt class="icon icon-location-pin">Office</dt>
    <dd>
      <a
        class="bux-link"
        href="https://maps.osu.edu/#data_s=id%3AdataSource_8-1916b96cc76-layer-20-1%3A1251"
        >4088 Postle Hall, 305 W. 12th Avenue, Columbus, OH 43210</a
      >
    </dd>
  </div>
  <div class="bux-icon-dl__item">
    <dt class="icon icon-link">Links</dt>
    <dd>
      <a class="bux-link" href="https://www.osu.edu"
        >A Day in the Life: Ken's blog</a
      >
    </dd>
  </div>
</dl>

{#
Buckeye UX - version 1.1.0
Copyright (C) 2025 The Ohio State University
#}

{#

Icon Description List

Available variables:

- list_items:   Array of list items.
- item.icon:    Name of the BUX UI Icon to display.
- item.term:    Term for the list item.
- item.desc:    Description / definition for the list item.

#}

{% set list_classes = "bux-icon-dl" %}
{% if _self.name != "default" %}
  {% set list_classes = list_classes ~ " bux-icon-dl--" ~ _self.name %}
{% endif %}

<dl class="{{ list_classes }}">
  {% for item in list_items %}
        <div class="bux-icon-dl__item">
        <dt class="icon icon-{{ item.icon }}">{{ item.term }}</dt>
        <dd>
          {{ item.desc }}
        </dd>
        </div>
  {% endfor %}
</dl>

Usage

Dos

• Use an “Unordered List” when you don’t need to convey a specific order for list items
• Use an “Ordered List” when the sequence or count of items is important
• Use a “Description List” with terms and descriptions, such as a glossary, or to display metadata, such as contact details
• Use an "Icon Description" List when data you are displaying is enhanced by having a user interface (UI) icon that supports each label.
• Use a UI icon to support the label, such as a calendar for “Date”.
• Always include an icon for each item in the description list.

Don’ts

• Don’t overuse lists for long-form or narrative content; rely on paragraphs
• If defining terms, like a glossary, use a Description List instead of the Icon Description List. The icon within an Icon Description List is not necessary, nor meaningful, for a glossary.
• Avoid displaying UI icons for some description terms, but not others.
• Do not use branded Standard icons in place of UI icons. Standard icons are designed to display larger than this component accounts for.

References

• U.S. Web Design System (USWDS) Lists