Guide 05 · Developer docs

Content types and custom entities

Which built-in type fits which purpose, how categories, tags, slugs, custom URLs and SEO settings behave across them, how revisions and publishing gate what the public sees, how to model a domain the platform has no type for, and where uploaded files live.

L1–L3

Unit 05 of 06 4 pages

Custom fields

Updated 23/10/2026 01:48

Custom fields add typed attributes to sixteen kinds of record, such as people, menu elements and forms, that layout areas do not cover. For content modellers and developers deciding where a value lives and reading it back.

Start with the rule: whether a value belongs in a layout area or a custom field, and the cases where the usual rule of thumb breaks. Then define a field in the admin, with its input type, validation and default, and check which records accept one at all. The unit ends with reading custom fields in both template engines and in an API response, including what an empty or misspelt field returns.

Writing custom fields through the API is covered in the APIs guide, on Custom fields.

In this unit

Read in order

01 Custom fields or layout areas A layout area belongs to a layout and its content lives in a record's revisions; a custom field belongs to a kind of record and is the same on all of them. The rule for choosing between them, and the cases where it bends. 02 Defining a custom field A custom field is defined once for an entity: a name, an input type, a label and help, a required switch and default content. What each setting does, the order fields take on the form, and what making a field required does to existing records. 03 Where custom fields attach Sixteen entities accept custom fields, from people and users to menu elements, forms, SEO settings and products. The full list, what each is typically used for, and the records that do not accept them. 04 Reading custom fields Custom fields are read with typed getters, the same in Smarty and Twig on every entity that has them, and the input type decides what comes back. Reading each kind, the empty case, and the shape in an API response.