# Reference and tags

A reference points at an entry in a collection and arrives in the view already loaded. Tags are short labels editors reuse across entries.

## Reference

`f.ref(() => collection)` picks one entry; `f.refList(() => collection)` picks several. The target is a function, so two collections can point at each other without an import cycle:

File: `components/sections/FavouriteArticles.schema.ts`

```ts
import { articles } from "@/smoodly/collections";
// …
  fields: {
    heading: f.text(),
    items: f.refList(() => articles).max(6),
  },
```

Editors see a search picker over the collection's entries in the language they are editing, each with its status. A list takes each entry once and stops at `.max()`.

## What the view receives

A reference resolves before render, in one batched read per collection, so the view gets the entry as `{ id, path, fields }` rather than an id:

File: `components/sections/FavouriteArticles.tsx`

```tsx
          {(items ?? []).filter((a) => a !== null).map((a, i) => (
            <ArticleCard key={i} article={a.fields} url={url(a.path!)} locale={locale} />
          ))}
```

An entry that is unpublished, or was deleted after the page went live, resolves to `null`, which is why the view filters before it maps. The value's type follows the target collection's fields.

The same rule holds in every read: sections, `q` lists and single reads, entry pages and globals. How deep a reference goes is the field's decision:

| Declaration | The view gets |
| --- | --- |
| `f.ref(() => authors)` | `{ id, path, fields }`; the author's own references stay id strings. |
| `.resolve("company")` | The named reference of the target resolved one level too. |
| `.resolve()` | The whole chain resolved. |

Types follow the depth, so `a.fields.company` is an id or a resolved entry as declared. One gap: where the chain meets a cycle it stops at ids, while the type says resolved.

## Where references may go

A reference lives at the top level of a section, element or collection schema. It cannot sit inside a list or an object, in a page field, or in an element that richtext embeds, because the reference index addresses fields by their top-level key. A schema that breaks the rule fails at startup with the path.

## Tags

`f.tags()` stores an array of short strings and shows them as chips. Editors type a tag and press Enter, or paste a comma-separated list, and pick from the tags other entries of the collection already use in that language:

File: `smoodly/collections.ts`

```ts
    tags: f.tags().localized(),
```

Tags are trimmed, and two that differ only in case are one tag: typing `design` when `Design` exists reuses it. `.min()` and `.max()` count tags. Each entry keeps its own list; there is no tag collection to manage. The starter shows an article's first tag on its card and all of them on the article page.

Next, [Conditional fields](https://smoodly.io/docs/fields/conditional.md).
