Skip to content
XenonDocs
Esc
    GitHub
    Docs

    Field helpers

    API reference for all field definition helper functions, option parameters, and return types in Xenon.

    On this page

    Overview

    You can define collection schema fields using helper functions exported from xenon-cms.

    TypeScript
    import {
      boolean,
      media,
      number,
      relation,
      richText,
      select,
      text,
      textarea,
    } from "xenon-cms";

    Each helper returns an object with a literal type discriminant and type parameters for compile-time inference.

    Common options

    All field helpers accept the following common options:

    OptionTypeDefaultNotes
    labelstringHumanized keyLabel displayed in the admin UI form.
    requiredbooleanfalseWhen true, rejects missing or null values during publishing.
    defaultValueField value typeundefinedValue populated for new records and used for null normalization.
    admin.descriptionstringundefinedHelp text displayed beneath the form control.
    admin.placeholderstringundefinedPlaceholder text shown while the input is empty (text, text area, number, select, relation and rich text fields).
    admin.hiddenbooleanfalseHides the field from the admin interface form.
    admin.readOnlybooleanfalseRenders the field as non-editable in the admin interface.
    admin.position"main" | "sidebar""main"Places the control in the main content canvas or sidebar.
    validate(value, ctx) => true | stringundefinedCustom validation function. Returning a string indicates an error message.

    text

    Single-line text input producing a string value.

    TypeScript
    title: text({ minLength: 3, maxLength: 200, pattern: /^[A-Z]/ })
    OptionTypeDefaultNotes
    minLengthnumberundefinedMinimum character length constraint.
    maxLengthnumberundefinedMaximum character length constraint.
    patternRegExpundefinedRegular expression pattern validation.

    textarea

    Multi-line text input producing a string value.

    TypeScript
    bio: textarea({ rows: 5, maxLength: 1000 })
    OptionTypeDefaultNotes
    minLengthnumberundefinedMinimum character length constraint.
    maxLengthnumberundefinedMaximum character length constraint.
    rowsnumber4Initial visible text rows in the admin UI.

    number

    Numeric input producing a number value.

    TypeScript
    quantity: number({ min: 0, max: 100, integer: true })
    OptionTypeDefaultNotes
    minnumberundefinedMinimum numeric value.
    maxnumberundefinedMaximum numeric value.
    integerbooleanfalseRestricts value to whole integer numbers.

    boolean

    Toggle switch producing a boolean value.

    TypeScript
    isFeatured: boolean({ defaultValue: false })

    select

    Dropdown or multi-select producing string literal unions.

    TypeScript
    category: select({
      options: [
        { label: "Guides", value: "guide" },
        { label: "News", value: "news" },
      ],
      hasMany: false,
    })
    OptionTypeDefaultNotes
    optionsreadonly (string | { label: string; value: string })[]RequiredArray of choices.
    hasManybooleanfalseWhen true, returns an array of selected option values.

    richText

    Formatted text editor producing a ProseMirror/Tiptap document object.

    TypeScript
    content: richText()

    Produces { type: "doc", content?: RichTextNode[] }.

    media

    Asset picker linking to an upload collection.

    TypeScript
    avatar: media({ relationTo: "media", hasMany: false })
    OptionTypeDefaultNotes
    relationTostringRequiredSlug of the target collection. Target must have upload: true.
    hasManybooleanfalseWhen true, produces an array of document ID strings.

    Produces string (doc id) or string[] when hasMany: true.

    relation

    Relationship picker linking to any collection.

    TypeScript
    author: relation({ relationTo: "authors", hasMany: false })
    OptionTypeDefaultNotes
    relationTostringRequiredSlug of any declared collection.
    hasManybooleanfalseWhen true, produces an array of document ID strings.

    Produces string (doc id) or string[] when hasMany: true.

    Next steps