List Block

The List block is used to group related items in a clear, scannable way. You’ll use it for steps, checklists, features, requirements, and any content that benefits from visual hierarchy and repetition.

Start here: watch the walkthrough (6 minutes)

Why use the List block

The List block goes beyond basic bullets and numbers. Editors can mix ordered and unordered lists at different nesting levels, apply custom bullet styles like arrows or checkmarks, and fine-tune how lists communicate structure.

Use the List block when you want to:

  • Present information in a structured, easy-to-scan format
  • Show sequences, steps, or priorities
  • Group related ideas without writing long paragraphs
  • Create nested lists that show hierarchy or relationships
  • Build visual patterns like checklists or multi-level outlines

Lists are especially helpful for readers who skim. When used well, they make content easier to understand, easier to navigate, and easier to remember.

How to use the block

Start by adding the List block to the page. Learn how to add blocks.

Once the block is added, editors typically:

  • Choose whether a list is ordered or unordered
  • Add list items
  • Build nested lists using indentation
  • Adjust list styles and numbering formats
  • Apply colors or styles for clarity and emphasis

The List block works at two levels:

  • The List block itself (which controls structure and styling for a level)
  • Individual List Item blocks inside it

Understanding that distinction makes advanced lists much easier to manage.

Block structure and nesting

A List block always contains List Item blocks.

When you indent a list item, WordPress automatically creates a new nested List block inside that item. Each nested level is its own list, with its own settings and styles.

This means:

  • Each level can be ordered or unordered independently
  • Each level can use different numbering or bullet styles
  • Nested lists are structurally correct and accessible by default

This structure is what allows ModernPress lists to be so flexible.

Block toolbar

The block toolbar appears above the List block or List Item when selected.

When the List block is selected

  • List type: Switch between ordered (numbered) and unordered (bulleted) lists
    • This applies only to the currently selected list level
  • Indent / Outdent:
    • Indent creates a nested list
    • Outdent moves the list back one level

Because each nested level is its own List block, you can change list types independently at every level.

When a List Item is selected

  • Indent / Outdent: Adjust the nesting level of that item
  • Bold / Italic: Apply inline emphasis
  • Link: Turn selected text into a link

These controls affect only the selected list item and its content.

Block settings

Block settings appear in the right sidebar while the List block is selected.

List style (ordered lists only)

Controls how numbers or markers appear for ordered lists.

Available options include:

  • Number
  • Uppercase letters (A, B, C)
  • Lowercase letters (a, b, c)
  • Uppercase Roman numerals (I, II, III)
  • Lowercase Roman numerals (i, ii, iii)

Start value

Sets the number (or letter) the list should start from. Start value applies only to the current list level This can be  useful when continuing a sequence across sections.

Block styles

Block styles are located in the Styles tab of the block settings sidebar.

Styles

These styles affect the bullet or marker appearance for the selected list level.

  • Default: Uses the standard bullet or numbering style
  • Arrow: Displays an arrow icon for each list item
  • Check: Displays a checkmark icon for each list item

These styles are available for both ordered and unordered lists and can be mixed across nested levels.

Color

Controls the text color for all list items within the selected List block.
Individual List Items also have color controls, but these should be used sparingly

Accessibility and content structure

The List block outputs proper HTML list markup (<ul>, <ol>, and <li>), which means:

  • Screen readers understand list structure and hierarchy
  • Nested relationships are communicated correctly
  • Keyboard and assistive technology navigation works as expected

Best practices for accessibility

  • Use ordered lists when sequence or order matters
  • Use unordered lists when items are related but not sequential
  • Nest lists only when there is a real hierarchy

All structural accessibility is handled automatically — your main responsibility is choosing the right list type and nesting intentionally.

Tips for editors

Start simple, then enhance

A basic list works perfectly for many situations. Add nesting, numbering styles, or custom bullets only when they improve clarity.

Be intentional with nested lists

Nested lists are powerful, but too many levels can be hard to follow. If a list feels complex, consider whether it should be broken into sections instead.

Change list type on nested levels

When you indent a list item, the new nested list defaults to an unordered list. If the structure calls for numbering, switch that nested level to an ordered list.

Apply color at the list level

If you need to change text color, apply it to the List block, not individual List Items. This keeps styles consistent and easier to manage.

Use keyboard shortcuts to work faster

Keyboard navigation makes building complex lists faster and more predictable.

  • Tab at the start of a list item: create a nested list
  • Shift + Tab: move back one level
  • Enter to add a new list item
  1. WordPress.org List Block documentation — please note that your block may have customizations affecting functionality, appearance, or available styles.