# List

Use the list content block to show a list of articles.

## Overview

The `list` block renders a list of articles.

### Default List

```yml
- _bookshop_name: list
  heading:
    title: Recent articles
    align: start
  input:
    section: tutorials
    reverse: true
    sort: date
  hide_empty: false
  background:
    color: body-tertiary
    subtle: false
  justify: start
```

### Filtered List

Add the following configuration to your page's frontmatter to enable data table features:

```yml
---
modules: ["simple-datatables"]
---
```

You can then use `sortable`, `paginate`, and `searchable` to enable inline sorting and filtering.

```yml
- _bookshop_name: list
  heading:
    title: Recent articles
    align: start
  input:
    section: tutorials
    reverse: false
    sort: date
  pagination: 5
  hide_empty: false
  background:
    color: body-tertiary
    subtle: false
  justify: start
  sortable: true
  paginate: true
  searchable: true
```

### Custom List

Customize the list by providing a `hook` partial.

```yml
- _bookshop_name: list
  heading:
    title: Recent articles
    align: start
  input:
    section: tutorials
    reverse: false
    sort: date
  hide_empty: false
  hook: assets/table-hook
  background:
    color: body-tertiary
    subtle: false
  justify: start
  sortable: true
```

Define the hook partial in your site's `layouts/_partials` folder. The following example renders a custom Markdown table consisting of the article's title and publication date.

```go-template
{{ $pages := .pages | default dict }}

{{ $content := printf "| %s | %s |\n|-|-|\n" (T "article") (T "published") }}
{{ range $pages }}
    {{ $content = printf "%s[%s](%s) | %s |\n" $content .LinkTitle .RelPermalink 
        (.PublishDate | time.Format "2006-01-02") 
    }}
{{ end }}

{{ return $content }}
```

## Arguments

The content block supports the following arguments:

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `background` | background |  |  | Background style of the section. |
| `bg-class` | string |  |  | Background class attributes of the element. It supports Bootstrap attributes to modify the background styling of the element. |
| `class` | string |  |  | Class attributes of the element. It supports Bootstrap attributes to modify the styling of the element. |
| `cover` | bool |  |  | Flag indicating if the element should be rendered fullscreen. |
| `filter` | string |  |  | Slice of category values used to render a filter button group above the element. Each value becomes a button label. An "All" button is always prepended. Uses the text content of the column at filter-col to match rows. |
| `filter-col` | int |  | `1` | Zero-indexed column number whose text content is matched against the active filter value. Defaults to 1. Only used when filter is set. |
| `fluid` | bool |  | `true` | Flag to set the section container to fluid design, else the section is limited to `xxl`. |
| `heading` | heading |  |  | Heading of the content block, including a preheading and content element. |
| `hide-empty` | bool |  |  | Hides the entire section when no pages are available. |
| `hook` | string |  |  | Render hook for the element's partial. |
| `input` | input | yes |  | List input of the element. Uses the name of the section to retrieve known pages. |
| `justify` | select |  | `start` | Justification of the child elements. Supported values: [`start`, `end`, `center`, `between`, `around`, `evenly`]. |
| `limit` | int |  |  | Maximum number of elements to display. |
| `overlay-mode` | select |  |  | Overlay mode of the element, overrides the site's general configuration. Supported values: [`light`, `dark`, `none`]. |
| `paginate` | bool |  |  | Flag indicating if pagination should be added to the element, if the list exceeds the maximum number of containing elements to display. |
| `pagination` | int |  |  | Number of elements per page in pagination, overrides site settings. |
| `pagination-select` | string |  |  | Sets the per page options in the dropdown. Must be an array of integers or arrays in the format [label (string), value (int)]. Requires `paginate = true`. It is recommended to configure values that are a multitude of the `pagination` value. |
| `searchable` | bool |  |  | Toggle the ability to search the dataset. |
| `section-class` | string |  |  | Section class attributes of the element. It supports Bootstrap attributes to modify the section styling of the element. |
| `sortable` | bool |  |  | Toggle the ability to sort the columns. |
| `theme` | select |  |  | Color theme to apply to the element. Supported values: [`light`, `dark`]. |
| `width` | int |  | `8` | Column width of the element. For embedded elements, the width is relative to the parent's container. |
| `wrap` | bool |  |  | Toggle the last column to wrap to a new row on smaller devices. This setting is not compatible with data tables. |
| `wrapper` | string |  |  | Class attribute of the element's wrapper. It supports Bootstrap attributes to modify the styling of the element. Icons include the `fa-wrapper` and `fa-fluid` attributes by default. |