# List

**List** is a key block type in Softr. You can link it to an Airtable base to build any collection of items such as a **job board,** **product listing, a ranked list** where users can upvote items, and so on. The block has a number of different layouts, which will be discussed in greater detail in the subsections to this article.

![List block layouts](https://3426011356-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M0NiyhsmXAcV5u1c6XK%2F-MPpoplVf1qIusW6cxtF%2F-MPpsJ8utumsyWttutb-%2F08_20_Blocks.png?alt=media\&token=6f403178-7828-472f-a95d-420297bdb153)

Now, let's find out what the common features of the block are and how they are configured.

To start with, you need to add your Airtable API key (learn how to find it [here](https://docs.softr.io/airtable/how-to-find-airtable-api-key)) in **Settings => Integrations => Airtable** to be able to import your list data from Airtable. \
\
Alternatively, you can just hit Setup Airtable in block settings and enter the API key in the pop-up that appears next. As soon as you click on Connect Airtable, your block settings will become available and you can start setting it up.

![Connecting Airtable from the block directly](https://3426011356-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M0NiyhsmXAcV5u1c6XK%2Fuploads%2FPepJeiF2s7lLx8EA4MHH%2Fsetup-airtable-b.png?alt=media\&token=b9e3539b-ee65-4bf7-8bab-e922696168ac)

In this section, we will not build a list but will rather review different list layouts and explore their specific features. So, let’s review the settings that are common for all the list layouts, and then we'll take a closer look at each layout in the subsections to this page.

## Data

After adding any of the list layouts from **Blocks => Dynamic => List**, you need to select the Airtable **Base** and **Table** where you want to import your data from. This is done from the **Data tab** of the block settings as shown below.

![Block's data tab](https://3426011356-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M0NiyhsmXAcV5u1c6XK%2Fuploads%2FyCalXjwtEUkliG9Q4nJo%2Fdata-b.png?alt=media\&token=2c7e975b-a7cc-4c2b-9a8c-493b83c28020)

As soon as you select your Base and Table, you'll the rest of the Data settings appear below. Let's take a look at those as well.

### Default View

Here, you can set one of your [Airtable table views](https://www.softr.io/airtable/airtable-views) as a default view, and the items in the list will be sorted and filtered according to the sorting and filtering configuration of that particular view. It can be a different type (e.g. "Calendar") or the same type but with different configuration (e.g. with different filters applied).

![Views on Airtable](https://3426011356-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M0NiyhsmXAcV5u1c6XK%2F-MPjn7uT6pIcAoQJaK3z%2F-MPjnQFOTACcltL-ldfz%2F2_b.png?alt=media\&token=e109e204-6d21-4c4d-a1ca-ac3a94a4d253)

### List Settings

#### Sort by

Here you have a list of available sorting options based on your Airtable fields (columns). Each field will have an ascending and descending order options (see below).

![Sort by](https://3426011356-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M0NiyhsmXAcV5u1c6XK%2Fuploads%2F6l2rjv3bu8QuZd1vd7bz%2Fsorting-b.png?alt=media\&token=13bf7bf3-0ab5-487d-8073-240dcbbc622c)

#### Items per page

You can choose how many items appear in the list by default. If there are more items to display, a **See More** button will be added at the end of the list, allowing the user to expand the list and view the additional items.

#### Items per row

You can also choose how many items ("**3"** or "**4"**) each row should contain.

{% hint style="info" %}
When there's an inline filter on the **Right** or on the **Left** the value is automatically set to "**3**" and can't be changed.
{% endhint %}

### **Empty state**

This field allows you to customize the message that's shown when the block can't fetch any results  for a given search query or due to some other reason.

### **Conditional Filters**

**Conditional Filters** allow you to filter the list for one or more users based on the defined conditions. Check out the [List Conditional Filters](https://softr.gitbook.io/softr-documentation/building-blocks/list-conditional-filters) section for more details.

## **Features**

Next, we have the **Features** tab, where we can configure some additional parameters for our list block as well as map the block fields to Airtable to specify what data needs to be displayed and how. Let's take a look.

### **Inline Filters**

Lists can have one or more **Inline Filters**, where you can define specific fields and their options, using which users can filter the list.

![Inline filters](https://3426011356-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M0NiyhsmXAcV5u1c6XK%2Fuploads%2FHXsffzU34xC0Wksa6HUa%2Finline-filters-b.png?alt=media\&token=f2caf152-8a59-4950-a821-76bc6b65e93e)

#### **Label**

Here you set the title of the filter.

#### **Filter by**

And this is where you choose which table field you want to have the list filtered by. All the table fields are available for selection (see below).

![Selecting a Filter by field](https://3426011356-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M0NiyhsmXAcV5u1c6XK%2F-MlFBveRJjipRj_1IsWR%2F-MlFEe9m4N9R4hw3fdOx%2Fselecting-filter-b.png?alt=media\&token=a4d58761-afd1-4407-acd0-d1108f1a01b2)

#### **Options**

Next, you need to set the available options for the selected fields. For instance, if you want to filter by the "Language" field, and it has "English" and "German" as its options, you can add any of these options here (separated by a semi-colon) to appear as the filter categories.

![Setting Filter options](https://3426011356-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M0NiyhsmXAcV5u1c6XK%2F-MlFBveRJjipRj_1IsWR%2F-MlFG-SFeiciQw59z8pT%2Ffilter-1-b.png?alt=media\&token=be5c4dbd-a856-45e9-beb4-16a5f3c39d5e)

However, if the selected **Filter by** fields's type is **single-** or **multi-select**, the options will be fetched from Airtable automatically. In the example below, we select the **Status** field which is single-select and has task status options on Airtable as shown below.

!["Status" field on Airtable](https://3426011356-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M0NiyhsmXAcV5u1c6XK%2F-MlFBveRJjipRj_1IsWR%2F-MlFHBmhCkemTLy5kbi-%2Fstatus-b.png?alt=media\&token=58deb167-ddf4-436b-8361-f1d583712dee)

Below you can see how the options are generated after selecting the field in **Filter by**.

![Selecting a single-select field](https://3426011356-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-M0NiyhsmXAcV5u1c6XK%2F-MlFBveRJjipRj_1IsWR%2F-MlFHKBpcKbWGofTzmHM%2FScreen%20Recording%202021-10-05%20at%2015.46.26.gif?alt=media\&token=38c10b94-d323-4ecd-a6bd-197bed5ac68e)

#### **Position**

Further on, you can set the position of your filter **(Top, Left,** or **Right)**.&#x20;

{% hint style="info" %}
Please, note that you **can't** have filters both on the **Left** and on the **Right**.
{% endhint %}

#### **Show as**

You can display the filter options as a **List** or **Dropdown** as shown below.

![Switching from List to Dropdown](https://3426011356-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M0NiyhsmXAcV5u1c6XK%2Fuploads%2FKfjDotQflNWSTmwCXDQC%2FScreen%20Recording%202022-07-12%20at%2019.16.41.gif?alt=media\&token=dbcec8f1-9c51-476c-9dca-2247beea1abd)

#### **Allow multiselect**

If you enable this, the users will be able to select more than one option at a time.

### Search Bar

#### Show Search Bar

Using this toggle you can remove the search bar from your list if you don't need it.

![Show/hide search bar](https://3426011356-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M0NiyhsmXAcV5u1c6XK%2Fuploads%2FjYyHTwzlJn3n7H8fmMCy%2FScreen%20Recording%202022-07-12%20at%2019.20.51.gif?alt=media\&token=a87dcb74-0070-4272-8391-ae5bba828966)

#### Placeholder Search Text

Here you can customize the text that appears within the search bar as a placeholder.

#### Search By

![Search by](https://3426011356-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M0NiyhsmXAcV5u1c6XK%2Fuploads%2FuNAhAO41tktrWjQ8OSJg%2Fsearch-by-b.png?alt=media\&token=6237a8b5-13c0-490e-b585-b6abc8c33bc7)

Under this option, you choose which fields the search is going to be performed by. You can add one or more fields, but if you don't add anything, the search will return all the list items for any query. Therefore, it's best to **select at least one field** for meaningful results.

### See More Button

Here, you can configure the **See More** button's (for showing more items in the list) label and styling.

### List Item

This is where you configure how the Airtable base is going to be mapped to your list. For each layout (discussed in subsections to this article), there is a default set of fields, for which you can set a corresponding field (**Content**) from your Airtable base or **hide** the field if you don't need it.

![Mapping the field and then hiding it](https://3426011356-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M0NiyhsmXAcV5u1c6XK%2Fuploads%2Ft0laHGelFGzSCskVqdDF%2FScreen%20Recording%202022-07-12%20at%2019.31.52.gif?alt=media\&token=6ae7bf77-ef6f-48f9-abc9-980d819c21cc)

Apart from that, you can add new fields using the **Add field** button. After adding the field, you need to specify its **Type** and set **Content** (corresponding Airtable field). For some types, there is also a **Label** parameter added (appears above the field content), which can be modified or removed if not needed.

![Adding a new field](https://3426011356-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M0NiyhsmXAcV5u1c6XK%2Fuploads%2Fm9UMumJq2MnIA8RKGF2G%2Flabel-field-b.png?alt=media\&token=18464b99-0a66-4c76-a223-a4e7ccf1c34f)

There is a variety of types to choose from, so let's go through them one by one:

* **Text** – plain text
* **Rich Text** – long text, [markdown](https://en.wikipedia.org/wiki/Markdown), or html
* **Headings** – different size headings
* **Email** – [mailto](https://en.wikipedia.org/wiki/Mailto) link
* **Url** – clickable Url
* **Button** – button with the standard list of actions (Open Page, Scroll to Section, Open External Url)
* **Tag** – for displaying one or more tags (e.g. if you have a multiselect field on Airtable with multiple values, they'll be displayed as multiple tags)
* **File** – provides a link for downloading attachments
* **Video/Audio** – for directly embedding audio/video content (e.g. from an Airtable Attachment field)
* **Image/Image Gallery** - for displaying a single or multiple images (within a gallery)
* **Embed** – can be used for embed snippets from different services (e.g. Calendly, YouTube, and so on)
* **Google Maps** – for Google Maps embed code
* **Rating** – for displaying a rating (Content can be a number from 1 to 5 or a "Rating" Airtable field)
* **Divider** – a simple divider line

### Clickable List Item

In this section, you can define what happens after clicking on the list item. By default, the Do Nothing options is selected, but there are 3 more options to choose from. So, let's see what each of those does.

#### Open External URL

This option allows you to select one of the table fields, which is supposed to contain URLs, so that each list item opens its own URL.

For example, if you are building a job board, the URL field can be the company website. Thus, after clicking on the list item, the user will be taken to the job posting's company page.

#### Open Page

The **Open page** option allows linking another page within the app. See below how that works.

![Open page option](https://3426011356-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M0NiyhsmXAcV5u1c6XK%2Fuploads%2Fr5up20chZXET0FaWQenP%2FScreen%20Recording%202022-07-12%20at%2019.58.15.gif?alt=media\&token=68138e00-b89d-421e-a7d0-cc4223987f17)

#### Open Modal

This option works similar to Open Page, but, instead of navigating to a new page, the user opens the page content inside a modal (i.e. a pop-up). Below, we've configured the modal to work similar to a [List Details block](https://softr.gitbook.io/softr-documentation/building-blocks/listing-details), where, for each list item ,the new page displays the details of that very item.

![Showing item details in a modal](https://3426011356-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M0NiyhsmXAcV5u1c6XK%2Fuploads%2F5g8nz5EjV1xaHj2GPiak%2FScreen%20Recording%202022-07-12%20at%2020.18.14.gif?alt=media\&token=f2878c3d-7b6d-4984-9ba4-97c289c1313d)

Finally, It's possible to select the **Size** of the modal from the 3 options available.

### Embed block

See how this works [here](https://softr.gitbook.io/softr-documentation/studio/pages/page-embed).
