> From the [Strife developer docs](https://strife.app/docs/reference/field-reference/fields.labels). Every page is listed in [llms.txt](https://strife.app/docs/llms.txt).

# fields.labels()

Pick from the team's labels, organized by group for browsing — the same picker used for the built-in labels base property — or limit the field to one label group with group: { id }.

Pick from the team's labels. Maps to editor `{ name: 'str-multi-select', type: 'label' }`.

Renders the same grouped picker as the built-in `labels` base property every document
already has (submenus per label group, plus an ungrouped section) — this builder adds an
**additional**, independently-valued field of the same kind, not a replacement for
`labels`. Without `group` it offers every one of the team's labels, like the base-properties
field. With `group` it offers one label group's labels only; see
[Limit the field to one label group](#limit-the-field-to-one-label-group).

## Example

```ts
fields.labels({ label: 'Topics' })
// _output: string[]

fields.labels({ label: 'Level', group: { id: process.env.LEVEL_GROUP_ID } })
// _output: string[]
```

## Options

| Option         | Type                          | Required | Description                                                |
| -------------- | ----------------------------- | -------- | ----------------------------------------------------------- |
| `label`        | `string`                      | Yes      | Label shown to editors in Strife Studio.                    |
| `group`        | `{ id: string \| undefined }` | No       | Offer only this label group's labels, named by the group's id. See [Limit the field to one label group](#limit-the-field-to-one-label-group). |
| `propertyName` | `string`                      | No       | Override the stored property name.                          |

No `options` and no `localizable` option.

## Limit the field to one label group

A type can have several label fields, each for its own kind of label, and each can be held to
one label group:

```ts
export const article = defineType({
  name: 'article',
  fields: {
    level: fields.labels({ label: 'Level', group: { id: process.env.LEVEL_GROUP_ID } }),
    topic: fields.labels({ label: 'Topic', group: { id: process.env.TOPIC_GROUP_ID } }),
  },
});
```

The group is named by its id, which never changes, so renaming the group, or creating another
group with the same name, doesn't affect the field. A group's id belongs to one team, so it is
read from the environment, the same way as a page id in `from`: one line per team in
`.env.local` or `.env`, prefixed with the team's key (`ACME_LEVEL_GROUP_ID`), which
`strife push` and `strife typegen` load from the project root. See
[Placing pages under a specific page](https://strife.app/docs/reference/cli/schemas.md#placing-pages-under-a-specific-page)
for how the lines are read.

To copy a group's id, open the team's settings in Strife Studio, go to **Content labels** (or
**Media labels**) and choose **Copy ID** in the group's row menu. The `list_labels` tool in the
[MCP server](https://strife.app/docs/tools/mcp-server.md) returns the id as well.

In Strife Studio, the field's picker then offers that group's labels only
(none while the group is empty), as one list instead of submenus:

* Labels the page already has from another group, or from no group, stay in the field and can
  be removed, but a label outside the group can't be added.
* An id that matches no label group in the team (the group was deleted, the variable holds
  another team's id, or the id was copied wrong) offers no labels at all, never the whole list.
  Studio's picker says that the field's label group is missing.

Like `from`, this is a Studio-side rule, not a server-side one: the API accepts any label, and
labels already on a page are untouched. The MCP tools follow it: `get_template` lists only the
group's labels as the values the field accepts, and a tool that writes another label into such
a field saves it and adds a warning to its answer. The limit is set only in `defineType`.

An unset variable never breaks compilation — the field is simply not limited — but
`strife push` and `strife typegen validate` refuse to continue when that happens
(`article: level.group.id is undefined — …`, with `(tab "…")` after `group.id` for a field in a
tab, naming the linked team's prefixed form), because the field would otherwise reach the
team offering every label and nobody would notice. Pass `--allow-missing-ids` to push or
validate anyway, with the field not limited and the warning kept. A `group` that isn't an
`{ id }` object fails to compile with an error naming the field.

It compiles to the editor's `options.labelGroupId` and needs `@strifeapp/strife` 1.25.0 or
later, which brings `@strifeapp/schema` 0.20.0 (update that too if you import from it
directly), plus `@strifeapp/cli` 0.1.0-alpha.20 or later for the refusal. With an older
`@strifeapp/strife`, `group` is not a known option (a type error when TypeScript checks the
schema) and is dropped, so the field offers every label; with an older CLI, nothing stops a
push whose variable is unset.

## Output type

`string[]` — one string per selected label, resolved live from the team's labels: the bare
label name while the label is ungrouped, `"<group name>/<label name>"` while it's grouped
(e.g. `["Färger/Blå", "Changelog"]`). Renaming a label or group updates the value without
republishing. The same value arrives on both paths a site reads it from — the `Content/ByUrl`
index for published content (`selectFields`) and live preview (`useState` / `subscribe` in
`@strifeapp/strife`) — so one handler serves both. The stored value is the array of selected
label ids; a site never sees those. A field limited to one group returns the same shape.
Querying, and the exact rules for grouped names:
[Label groups](https://strife.app/docs/reference/database/label-groups.md#field-level-label-pickers).

## See also

* [`fields.multiSelect()`](https://strife.app/docs/reference/field-reference/fields.multiselect.md) — a flat, ungrouped array-of-values
  picker; use this instead when the choices aren't the team's label taxonomy.
