# Elements

> Add text, number, choice, image and other elements to a type, pick the right kind for each detail, and reuse one element across several types.

An element is one field that editors fill in for an entry, such as "Opening hours", "Photos" or "Price". This page explains how to add elements to a type, which kind to choose for each piece of information, and how reuse works. It is for project Owners, who set up the content model.

## What is an element?

An element (field) is a single piece of information on an entry. You create it once in a project and can assign it to as many types as you like: one "Description" element can serve stores, trails and events. Each element has a **kind** that decides what it holds, such as text, a number, photos or a date.

In the app, elements live in **Content model** on two tabs: under each type's **Assigned elements** on the **Types** tab, and all together on the **Elements library** tab.

## How do I add elements to a type?

1. Open **Content model**, stay on **Types**, and select the type.
2. Under **Assigned elements**, click **Assign element**.
3. Pick an existing element from the list, or choose **Create new element…** to make a new one (see [How do I create an element?](https://spatibase.com/docs/model/elements/#how-do-i-create-an-element)).
4. Drag a row by its handle (it shows when you point at the row) to change the order. The order here is the order of the fields in the entry form.
5. Click an element's name to open its settings. It is the same element as in the **Elements library**, so changes apply to every type that uses it.

To take an element off a type, hover its row and click the remove button (**Remove from this type**). The element stays in the library, and entries keep their stored values. See [Change the model safely](https://spatibase.com/docs/model/change-the-model/).

### Add a field while editing an entry

The quicker way for a common field: in the entry editor on **Entries**, click **Add field** below the fields and pick a starter field (**Description**, **Photos**, **Address**, **Website**, **Contact details**, **Opening hours**, **Date and time**, **Category**) or **Custom field…** (a **Name** and a **Kind**). Spatibase creates the element, or reuses one in the library with the same identifier and kind, and assigns it to the entry's type at the end of its **Assigned elements**. Only Owners see **Add field**. See [Add a field from the entry](https://spatibase.com/docs/content/entries/#add-a-field-from-the-entry).

On a type you are still creating, assigned elements are saved together with the type when you click **Create type**. On an existing type, changes to **Assigned elements** are saved straight away.

## How do I create an element?

Choose **Create new element…** while assigning, or click **New element** on the **Elements library** tab.

On the left, the **New element** window lists every **kind of content** (what sort of value the element holds, see the table below), in groups such as Text, Media & files and Places. The search box is focused when the window opens: type "date", use the up and down arrow keys to move through the list, Enter to tick a kind, and Tab to go to the form. You pick the kind here and can't change it afterwards, because entries already store values in that format.

On the right is the form for the selected kind:

- **Label**: what editors see, for example "Opening hours". It starts as the kind's name, for example "Date & time".
- **Identifier**: the name developers use in the API. It is suggested from the label; you can change it. See [What can an identifier look like?](https://spatibase.com/docs/model/change-the-model/#what-can-an-identifier-look-like).
- **Help text** (optional): shown to editors behind an (i) next to the field's label.
- **Required**: entries can be saved as drafts without it, but can't be marked ready to publish until it is filled in.
- **Settings for the kind**: for example the options of a Choice, or the unit of a Number.

Click **Create element**. If you started from a type, the new element is assigned to it right away.

### Can I create several elements at once?

Yes. Each kind keeps its own details while the window is open, so you can switch kinds without losing what you typed. A green dot marks a kind you have filled in; a red dot marks one that needs fixing. Tick the box at the right end of each kind you want to create (it appears when you point at the row, and is always shown on touch screens). The button changes to **Create 3 elements** (for three ticked kinds) and creates them all in list order. With nothing ticked, **Create element** creates only the kind you are looking at.

## What kinds of elements are there?

Pick the kind that matches the information, not the one that looks closest: a Choice gives you clean filters, a Number can be sorted and compared, a Date can be checked for ranges.

| Kind | What it holds | Settings you can set |
|---|---|---|
| **Text** | A name, short phrase or paragraph of plain text | **Editor type**: **Single line**, **Multiple lines** or **JSON (for developers)**; minimum and maximum length |
| **Rich text** | Formatted text with headings, lists, links and images | None |
| **Images** | One or more uploaded photos or graphics | Minimum and maximum number |
| **Contact** | Name, email, phone, website and address | None |
| **Number** | A number such as a price, rating or capacity | Smallest and largest allowed, **Unit** (such as km, €, people), **Whole numbers only** |
| **Yes / No** | A simple on/off switch | None |
| **Date & time** | A date, a time, or both, optionally as a start and end | **Date only**, **Date and time** or **Time only**; **Start and end (a range)** with shortest and longest allowed |
| **Choice** | One or several options from a list you define | The options (with sub-options up to 4 levels), **Allow picking several options**, pick at least and at most |
| **Link** | A web address with an optional label | None |
| **Files** | Uploaded documents such as PDFs | Minimum and maximum number, **Allowed formats** (such as .pdf, .docx) |
| **Color** | A color, for example for a map marker or label | None |
| **Reference** | A link to another entry, for example a store's region | **Link to entries of type** (entries of their subtypes can be linked too; none ticked allows any type), **Allow linking several entries**, link at least and at most |
| **Map shapes** | Extra places or shapes on the map, for example a delivery area or parking spots | **Allowed shapes**, **Up to how many shapes?** (1 to 100), **Map feature types** |
| **ID / slug** | A unique code or web-address slug, for example for links or matching imports | Minimum and maximum length (up to 255 characters), **Offer "Generate from title"** |
| **Embed** | A YouTube, Vimeo, Spotify or SoundCloud link shown as a player | **Allowed providers** |
| **Location** | A single place given by coordinates, with an optional address | None |
| **Phone** | A phone number | None |

For a **Choice**, list the options under **Options**: **Add option** adds one at the end, drag an option by its handle (it shows when you point at the row) to change the order, **›** makes it a sub-option of the one above and **‹** moves it back up a level, **+** adds a sub-option under it (up to 4 levels), and × removes it. Each option has a label and a value; the value is what the API sends. A Choice can have up to 1000 options, and each value can be used only once. Entries that use an option you remove keep their value, but the API shows nothing for it until an editor picks a current option. If entries use an option you remove, or whose value you change, **Save element** first asks “Remove an option that entries use?” with how many entries use it and how many of those are published; **Save anyway** saves, **Cancel** keeps the options. Changing only a label never asks.

In a project with [languages](https://spatibase.com/docs/content/translations/), each option also has a **Translations** section: click it to type what the option is called in each other language. A language you leave empty shows the main label. The value stays the same in every language.

### Which kind should I use when?

- **Text or Rich text?** Use **Text** for short, plain values such as a name or opening hours. Use **Rich text** when editors need headings, lists or links, such as a description.
- **Choice instead of Text** for anything people filter by, such as a category, difficulty or service. Free text gives you "Wifi", "WiFi" and "wi-fi"; a Choice gives you one value.
- **Reference instead of Text** when the value is another entry in your project, such as the region a store belongs to. The link stays correct when the other entry is renamed.
- **Map shapes or Location?** The type's own location already places the entry. Use **Map shapes** for extra drawn shapes that belong to the entry (a delivery area, parking spots, a route's trailheads). Use **Location** for a second point given as coordinates, such as a meeting point. Neither affects where the entry sits on the map or the API's location filters.
- **ID / slug** when a website builds addresses from your content (`/stores/main-street`) or when you want imports to update existing entries instead of creating duplicates. Each value must be unique.

## How does reusing elements work?

An element is defined once per project and can be assigned to any number of types. The **Elements library** tab lists every element with its **Identifier**, where it is **Used in**, and whether it is **Required**.

Because it is the same element everywhere, editing it changes it on every type that uses it. For example, adding an option to a "Services" Choice makes the new option available on every type with "Services". If two types need different settings, create two elements.

On the **Elements library** tab you can also:

- type in the **Filter** box next to the **New** button to narrow it down (by name, identifier, kind or type; capitals and accents don't matter). Long lists show 50 at a time, with a **Show more** button below;

- edit an element with the pencil button (**Edit**) at the end of its row;
- **Archive** an element you no longer need (the archive button next to it). It is removed from every type that uses it, and existing values are kept. An archived element keeps its identifier, so no new element can use it;
- tick **Show archived** and click **Restore** to bring an archived element back into the library. Then assign it to the types that need it again; their entries' stored values reappear.

> **Tip:** Name elements for editors ("Opening hours") and keep identifiers short and stable (`opening-hours`). Websites and apps read values by identifier, so changing it later breaks them.

## Related

- [Types](https://spatibase.com/docs/model/types/)
- [Map feature types](https://spatibase.com/docs/model/map-feature-types/)
- [Change the model safely](https://spatibase.com/docs/model/change-the-model/)
- [Field values in the API](https://spatibase.com/docs/reference/field-values/)