# Custom Fields
Custom fields let you attach structured data to every task in a Team Project. Sprint number, story points, a design link, a client name: if it matters to your team's workflow and isn't covered by the built-in fields, a custom field is the answer.
See also: [[Managing Team Tasks]] for how fields appear on tasks, and [[Setting Up a Team Project]] for where to add them during initial setup.
> [!quote] Fields for your workflow, not the other way around
> Built-in fields cover the basics: status, priority, assignees and dates. Custom fields cover the rest: whatever your team actually tracks that the defaults don't.
## Where custom fields live
Custom fields are defined **per project** in **Settings → Custom Fields**. Once added, they appear:
- On every task in that project (in the Properties panel and inline in List view)
- As optional columns in [[Team List|List view]]
- In [[Time Tracking and Settings#Saved views|saved views]] that include those columns
---
> [!note] Fields become form questions on a Service Desk
> On a [[Service Desk]], the fields you define here are what you can ask about on a public [[Intake Forms|intake form]]. A field you set up for triage doubles as a question for the requester.
## Field types
![[team-custom-field-editor.png|508]]
| Type | What it stores | Best for |
| ---------- | --------------------------- | -------------------------------------------------------- |
| **Text** | Any short string | Labels, free-form notes, client names, environment names |
| **Number** | A numeric value | Story points, estimates, bug counts, weight |
| **Date** | A date picker value | Secondary deadlines, target dates, review dates |
| **URL** | A link | Figma files, specs, pull requests, Notion pages |
| **Member** | A team member | Reviewer, approver, secondary owner, point of contact |
| **Select** | One value from a fixed list | Sprint, phase, priority tier, client, category |
> [!tip] URL fields render as clickable favicon links
> Paste any URL into a URL field and Zaphiri renders it as a clickable favicon link directly on the task, showing the site's favicon alongside the link. There is no hunting through descriptions for the Figma link.
> [!note] Select vs. text
> Use a select field when the options are known and finite (sprint names, client list, phases). Use text when the value varies freely. Select fields are also filterable and groupable in List view; text fields are not.
---
## Filter tasks by a field
Use **Filter > Add filter** in [[Team List]] to choose a field and value. Matching subtasks remain grouped beneath their parent for context, with non-matching siblings hidden. Combine the field with status, priority, or assignee filters when you need a narrower view.
## Adding a custom field
1. Open the project and go to **Settings → Custom Fields**
2. Click **Add field**
3. Enter a name and choose a type
4. For **Select** fields: add the options you'll start with (you can add more later)
5. Optionally assign colours to select options (see below)
6. Save
The field is immediately available on all tasks in the project. It also appears in **Settings → Columns** so you can add it to List view.
> [!tip] Name fields clearly
> The field name appears on task cards, in column headers, and in the Properties panel. Use a short name that's obvious without context: "Sprint", not "Current Sprint Number".
---
## Select field options and colours
Select (dropdown) fields support:
- **Adding options**: add as many as you need, in any order
- **Duplicate names are caught**: adding or renaming an option to a name that already exists shows a message asking you to choose another name
- **Option colours**: assign a background colour to each option so values are easy to scan on the board, including a **no color** option if you'd rather leave a value without a colour
Colour-coded select options are especially useful for fields like sprint (each sprint a different colour) or phase (colour shows the stage).
> [!example] Sprint field with colours
> Sprint 1 → blue, Sprint 2 → green, Sprint 3 → purple. At a glance, you can tell which sprint a task belongs to without reading the value.
---
## Editing and deleting fields
From **Settings → Custom Fields**:
- **Rename** a field: the new name reflects everywhere immediately
- **Reorder**: drag a field to a new position in the list; the new order reflects wherever fields are shown
- **Add or remove options** on a select field: tasks with a removed option keep the old value until someone updates the task
- **Rename or recolour an option**: select values are stored by the option's stable ID, not its literal text, so a rename or recolour updates instantly everywhere it's shown (task chips, columns, filters, saved views) with no need to touch existing tasks. Renaming an option shows a confirmation first, since it changes what every task already using it displays
- **Delete a field**: removes the field and all its values from every task in the project. This cannot be undone.
Because deleting a field is destructive, Zaphiri asks you to confirm deliberately:
![[team-custom-field-delete-confirm.png|420]]
- The confirmation shows **how many tasks currently have data** in the field, counted across the whole project, including Done and Backlog tasks
- **View these tasks** closes settings and filters the [[Team List|list]] to the affected tasks with the field's column visible, so you can review what would be lost before deciding
- Deleting requires **typing DELETE** before the confirm button enables, so a stray click cannot wipe the field
> [!warning] Deleting a field removes all data
> When you delete a custom field, every task in the project loses its value for that field permanently. Rename or hide a field rather than deleting it if you think you may need the data.
---
## Using fields in List view
Once a field exists, you can show it as a column in [[Team List|List view]]:
1. Go to **Settings → Columns** to add the field to the project default layout
2. Or use the column picker in List view to toggle it on for your personal layout
In List view, custom field cells are **inline-editable**. Click a cell to set or change the value without opening the task.
> [!highlight] Inline editing saves time
> Set sprint, story points, or reviewer directly on the list row during planning or triage. No need to open each task.
---
## Filtering and grouping by custom fields
In List view, select fields (dropdowns) can be used to **group** or **filter** the list:
- **Group by** a select field to organise tasks by sprint, phase, or category
- **Filter** to show only tasks with a specific value
Text, number, date, URL, and member fields appear on tasks and in columns but do not support grouping.
> [!tip] Save your grouped views
> After grouping by sprint or phase, save the view as a team view so everyone on the project can open it in one click. See [[Time Tracking and Settings#Saved views|Saved views]].
---
## Custom fields in the task panel
On any open task, custom fields appear in the **Properties panel** on the right alongside status, priority, assignees, and dates. The panel can be collapsed to give descriptions and comments more room. Zaphiri remembers your preference.
If a long field name is shortened in the Properties panel, hover over it, focus it with the keyboard, or tap it to read the full name.
![[team-custom-field-full-name.png|431]]
> [!success] Fields follow the task
> Custom field values are part of the task record. They appear in the task panel, on the board, in saved views, and in the [[API Reference/Team|Team API]]. Wherever the task is, the fields travel with it.
---
**Next:** See how to configure all project settings in [[Time Tracking and Settings]], or return to the [[Team Projects]] overview.