Lists

One of the most common HTML constructs are lists (ordered or unordered), and any web application ends up having many of them, either for listing items or for components that do not even look like lists, but for the purposes of marking up, an ul or ol fits the bill best. Luckily, Drupal has always had the item_list theme hook which is flexible enough to allow us to use it in almost all cases.

The item_list theme hook is defined inside drupal_common_theme(), is preprocessed (by default) in template_preprocess_item_list(), uses the item-list.html.twig template by default, and has no default theme hook suggestions (because it's so generic and registered outside the context of any business logic). If we inspect its definition, we'll note that it takes a number of variables that build up its flexibility. Let's take a look at an example of how to use it.

Imagine that we have the following array of items:

$items = [
  'Item 1',
  'Item 2'
];

The simplest way we can render this as an <ul> is as follows:

return [
  '#theme' => 'item_list',
  '#items' => $items
];

Do note that the respective <ul> is wrapped in a <div class="item_list"> and that the items in our array can also render arrays themselves.

If we want to change the list into an <ol>, we set the #list_type variable to ol. We can even have a title heading (<h3>) before the list if we set the #title variable. Moreover, we can add more attributes on the <div> wrapper. For more information on how the other options work, I suggest that you inspect the template file and preprocessor function. However, these are the ones you'll most often use.