Fields

Every field type kitcms supports, with its options and how it is stored.

On this page

This page documents the field builders from fields (usually imported as f): the options every field shares, then each field type.

import { fields as f } from '@kitcms/core';

A field's name is its key in the fields record. Builders compute the field's TypeScript type from the options you pass, so required: true makes the value non-null on read.

Options every data field has

Option What it does
label Admin label. Default: the field name in sentence case.
required The value must be present and non-empty. Required fields are non-null on read.
defaultValue Used on create when the input omits the field. A function is called once per create.
validate Custom validation. Runs on the server only. Return true (or nothing) when valid, or an error message.
access Field-level rules { read, create, update }. Booleans only. A denied read removes the field from the result. A denied write keeps the old value.
hooks Field hooks: beforeValidate, beforeChange, afterChange, afterRead. See Hooks.
admin Admin presentation, below.

Built-in rules (required, min, maxLength and so on) run in the browser and on the server. Custom validate functions and admin.condition run on the server only.

f.text({
	validate: (value) => !value || /^#[0-9a-f]{6}$/i.test(value) || 'Use a hex colour such as #1f4e79.',
});

Admin options

Option What it does
description Help text under the input.
readOnly Shown but not editable in the admin. Server-side writes still go through field access.
hidden Not rendered in the admin. The value is still stored and returned.
position 'sidebar' puts the field in the edit view's side column. Default 'main'.
width CSS width inside a row, such as '50%'.
placeholder Input placeholder.
condition (data, siblingData) => boolean. Shows the field only when it returns true. Evaluated on the server on load and on every save. A hidden field keeps its value and skips validation.

Column options

text, email, slug, number, select and date can also set:

Option What it does
index Adds a database index.
unique Adds a unique index. A duplicate fails with a field error.

Text fields

text

A single line of text.

Option What it does
minLength, maxLength Length limits.

textarea

Multi-line text. Takes minLength and maxLength, and admin.rows for the height.

email

A text field that must be an email address.

slug

A URL-safe string (lowercase letters, digits and single dashes).

Option What it does
from Name of a sibling field. When the input leaves the slug empty, kitcms fills it from that field.
slug: f.slug({ from: 'title', unique: true, admin: { position: 'sidebar' } }),

A slug with from is optional on create.

Numbers, booleans and dates

number

Option What it does
min, max Value limits.
integer Only whole numbers are valid.
admin.step Input step.

checkbox

A boolean. It is never null and defaults to false. It has no required option. Takes defaultValue and index.

select

One value from a list.

Option What it does
options Required. Strings, or { label, value } objects.
status: f.select({ options: ['draft', 'published'], defaultValue: 'draft', required: true }),
tone: f.select({ options: [{ label: 'Calm', value: 'calm' }, 'bold'] }),

With a literal list, the value type is the union of the values.

date

An ISO 8601 string in documents. In the database it is an integer of milliseconds, so it sorts and filters correctly.

Option What it does
admin.picker 'day' or 'dayAndTime'.

Rich content

richText

A rich text document, edited with a Tiptap editor and stored as JSON. The value type is RichTextDoc.

Render it on your site with the helpers from @kitcms/core/richtext:

import { toHTML, toPlainText } from '@kitcms/core/richtext';

const html = toHTML(page.body);

toHTML escapes every text and attribute and checks link URLs against an allow-list of schemes, so its output is safe to inject. Options: nodes and marks for custom renderers (their output is trusted, so escape anything you take from node attributes), and linkRel. Also exported: escapeHTML, safeHref, isRichTextDoc.

json

Arbitrary JSON, stored in a text column. It is never required. Pass the stored shape as a type argument:

hours: f.json<{ day: string; open: string; close: string }[]>(),

Relationships and files

relationship

A link to a document in another collection.

Option What it does
relationTo Required. The slug of the target collection.
hasMany Store an ordered list of IDs. The value is then never null: it defaults to [].
minRows, maxRows Limits for hasMany.

On read, the value is an ID. Use depth to load the documents (see The Local API). You can filter by a single relationship, and by hasMany relationships with contains, in and not_in.

upload

A relationship to an upload: true collection. It takes the same options as relationship.

cover: f.upload({ relationTo: 'media' }),
gallery: f.upload({ relationTo: 'media', hasMany: true }),

See Media.

Structure fields

group

A named object of fields. It is never null on read and is stored as one JSON column.

seo: f.group({
	fields: {
		metaTitle: f.text({ maxLength: 70 }),
		metaDescription: f.textarea({ maxLength: 160 }),
	},
}),

Takes fields, plus the shared options except required and defaultValue.

array

A list of rows that share the same fields. Each row gets a stable id. It is stored as one JSON column.

Option What it does
fields Required. The fields of one row.
minRows, maxRows Row count limits.
labels { singular, plural } for the admin.

blocks

A list of blocks, where each block is one of the block types you list. See Blocks.

Option What it does
blocks Required. Block types made with block().
minRows, maxRows Block count limits.
labels { singular, plural } for the admin.

Layout fields

Layout fields only change how the edit view looks. They hold no data of their own: their child fields are stored as if you declared them next to the layout field.

Field What it does
row row({ fields }) puts its fields side by side. Use admin.width on children.
collapsible collapsible({ label, fields, admin: { initCollapsed } }) is a titled, collapsible section.
tabs tabs({ tabs: [{ label, description?, fields }] }) splits the edit view into tabs.
content: f.tabs({
	tabs: [
		{ label: 'Content', fields: { body: f.richText() } },
		{ label: 'SEO', fields: { seo: f.group({ fields: { metaTitle: f.text() } }) } },
	],
}),

Here body and seo are top-level fields of the document. The key content is only a name for the layout field.

What you can filter on

where works on id, createdAt, updatedAt, every top-level column field and top-level hasMany relationships. Fields stored as JSON (group, array, blocks, json, richText) cannot be filtered. See The Local API.

Edit this page on GitHub