Admin Field Types — Total CMS 3

Every schema property carries a field and a type. The field decides how the admin edits the value; the type decides how it is stored. Pick the field first — when a property omits type, Total CMS fills it in from the field on save, so one well-chosen setting gives you the right editor, the right storage shape, validation and the matching Twig filters without further work.

The rule that matters most is to match the field to the shape of the value, and use text only when nothing more specific fits. A date in a text field cannot be filtered by “this month”. A number in a text field sorts as a string. A yes/no in a text field is a typo waiting to happen. Every one of those has a field built for it: date and datetime, number, price and range, toggle and checkbox. Beyond those, styledtext for article bodies, email and url validated on entry, secret for tokens, color stored as hex and OKLCH, image, gallery, file and video for media, and card and deck for structure.

Choosing between the list-shaped fields is where content models are won or lost. A select is right when the choices are fixed. A list with propertyOptions is right when editors will keep adding to them: it offers every value already used in the collection as a suggestion while still allowing new ones, so a tag vocabulary grows with the content. That is how the built-in blog schema's categories and tags work.

Settings that work on any field add another layer. autogen composes a value from other properties and built-in variables — ${title}, uuid, currentyear — and slugifies the result on an id field. calc turns a number or price field into a read-only computed value, with arithmetic, rounding, and aggregates like sum(${items.lineTotal}) across a deck's items. visibility shows or disables a field based on another field's value, and required makes that conditional — so a notification email can appear and become mandatory only when the toggle above it is on.

When you are not sure which field to reach for, copy from the source. Total CMS ships a reserved schema named totalcms that demonstrates every built-in field type with its settings in one valid file. Read it in the schema editor, over MCP, or with tcms schema:get totalcms --json.

What you get

Match the field to the value

A date field filters by date, a number field sorts numerically, an email field validates. Text is the last resort, not the default.

Vocabularies that grow

A list field with propertyOptions suggests every value already used in the collection while still accepting new ones — tags without schema edits.

Fields that compute themselves

calc makes a number or price read-only and derived, with round, min, max and aggregates such as sum(${items.lineTotal}) across a deck.

Show fields when they matter

visibility watches another field and hides or disables this one. Pair it with required and the rule only applies when the field is actually on screen.

A reference schema to copy

The reserved totalcms schema demonstrates every field type and setting in one valid file. Find the property that matches your value and adapt it.

In practice

One snippet

# Read the reference schema that demonstrates every field type
vendor/bin/tcms schema:get totalcms --json

# Check your own schema before calling it done
vendor/bin/tcms schema:lint article --strict

The reference schema is the fastest way to find the right field, and lint is the fastest way to find the fields you left undocumented.

FAQ

Common questions

Which field should I use for categories?

It depends what you mean. Editors adding their own, several per object: a list field with propertyOptions. A fixed dropdown, one per object: a select with static options. Several fixed choices: a checklist.

Can a field be required only sometimes?

Yes. Combine the field's required setting with visibility, and leave the property out of the schema's top-level required array — otherwise the server-side rule rejects the save regardless of the toggle.

Are the localized fields available on every edition?

No. localizedtext, localizedtextarea and localizedstyledtext are used inside custom schemas, which are a Pro feature, so Lite and Standard cannot create or edit them.

Can I add a field type of my own?

Yes. Extensions can register custom field types alongside the built-in ones, and they appear in the schema editor like any other.

Related features

Want the details? Read the 36+ admin field types documentation →

Or keep browsing: every Total CMS feature →

Start Your Free 45-Day Trial

A purpose-built editor for every value