Field Types Reference

{
  name: 'title',
  type: 'text',
  label: 'Title',
  required: true,
  unique: true,
  admin: { description: 'Shown as the public page heading.' },
}

{
  name: 'title',
  type: 'text',
  label: 'Title',
  required: true,
  admin: { placeholder: 'Enter a title…' },
}

{
  name: 'excerpt',
  type: 'textarea',
  label: 'Excerpt',
  maxLength: 160,
  maxWords: 30,
}

{
  name: 'summary',
  type: 'textarea',
  label: 'Summary',
  admin: { description: 'A short plain-text summary for cards.' },
}

{ name: 'body', type: 'richText', label: 'Body', required: true }

{ name: 'contactEmail', type: 'email', label: 'Contact email' }

{ name: 'featureIcon', type: 'icon', label: 'Feature icon' }

import * as icons from 'lucide-react'

export function DynamicIcon({ name }: { name: string }) {
  const Icon = icons[name as keyof typeof icons]
  return typeof Icon === 'function' ? <Icon aria-hidden /> : null
}

{ name: 'callToAction', type: 'url', label: 'Call to action' }

{
  "type": "internal",
  "url": "/blog/a-post",
  "relationTo": "posts",
  "value": "post-id",
  "label": "Read the post"
}

export const Posts = defineCollection({
  slug: 'posts',
  admin: { urlPattern: '/blog/{slug}' },
  fields: [
    { name: 'title', type: 'text', label: 'Title' },
    { name: 'slug', type: 'text', label: 'Slug' },
  ],
})

{ name: 'price', type: 'number', label: 'Price', defaultValue: 0 }

{
  name: 'featured',
  type: 'boolean',
  label: 'Featured',
  defaultValue: false,
  admin: { layout: 'switch' },
}

{ name: 'eventDate', type: 'date', label: 'Event date' }

{ name: 'publishedAt', type: 'datetime', label: 'Published at' }

{ name: 'openingTime', type: 'time', label: 'Opening time' }

{
  name: 'status',
  type: 'select',
  label: 'Status',
  options: [
    { label: 'Draft', value: 'draft' },
    { label: 'Published', value: 'published' },
  ],
}

{
  name: 'topics',
  type: 'multiSelect',
  label: 'Topics',
  options: ['engineering', 'design', 'business'],
}

{
  name: 'author',
  type: 'relationship',
  label: 'Author',
  relationTo: 'users',
  required: true,
}

{
  name: 'posts',
  type: 'join',
  label: 'Posts',
  collection: 'posts',
  on: 'author',
  limit: 20,
}

{
  name: 'seo',
  type: 'object',
  label: 'Search metadata',
  fields: [
    { name: 'title', type: 'text', label: 'Meta title' },
    { name: 'description', type: 'textarea', label: 'Meta description' },
  ],
}

{
  name: 'questions',
  type: 'array',
  label: 'Questions',
  fields: [
    { name: 'question', type: 'text', label: 'Question', required: true },
    { name: 'answer', type: 'textarea', label: 'Answer', required: true },
  ],
}

{
  type: 'row',
  fields: [
    { name: 'firstName', type: 'text', label: 'First name', admin: { width: '50%' } },
    { name: 'lastName', type: 'text', label: 'Last name', admin: { width: '50%' } },
  ],
}

{
  name: 'scheduledAt',
  type: 'datetime',
  label: 'Scheduled at',
  admin: { condition: "status == 'scheduled'", tab: 'Publishing' },
}

{
  name: 'internalNotes',
  type: 'textarea',
  label: 'Internal notes',
  access: {
    read: ({ user }) => user?.roles?.includes('admin') ?? false,
    update: ({ user }) => user?.roles?.includes('admin') ?? false,
  },
}

export type ArrayField = TypedField<"array", unknown>;

export type AuthDocFields = {
  email: string;
  password?: string;
  roles?: string[];
};

export interface AuthenticatedUser {
  /** The user's document ID in the database. */
  sub: string;
  /** The user's email address. */
  email?: string;
  /** Slug of the collection this user was authenticated against. */
  collection: string;
  /** Array of role strings, if your auth collection has a `roles` field. */
  roles?: string[];
  /** Any additional fields from the auth collection document. */
  [key: string]: unknown;
}

export interface BaseFieldAdmin {
  /** Placeholder text shown when the input has no value. */
  placeholder?: string;
  /** Custom component key registered in the Admin UI. */
  component?: string;
  /** Help text rendered below the field. */
  description?: string;
  /** Hides the field from the Admin form without deleting stored data. */
  hidden?: boolean;
  /** Excludes the field from Admin list filtering. */
  filterable?: boolean;
  /** Renders the field as non-editable in the Admin UI. */
  readOnly?: boolean;
  /** Hides the field's label in the Admin form (e.g. single-field array rows where the label is redundant). */
  hideLabel?: boolean;
  /** Reactive condition controlling whether the field is visible in the Admin UI. */
  condition?: ((data: Record<string, unknown>, siblingData: Record<string, unknown>) => boolean) | string;
  /** Tab name used when the edit form is rendered as tabs. */
  tab?: string;
  /** CSS width hint used when the field appears inside a `row`. */
  width?: string;
}

export interface Block {
  /** Stable identifier stored in each block row as `blockType`. */
  slug: string;
  /** Human-readable labels shown in the Admin block picker. */
  labels?: {
    /** Singular label, for example `Hero`. */
    singular: string;
    /** Plural label, for example `Heroes`. */
    plural: string;
  };
  /**
   * Lucide icon name shown on the block card and in the block library.
   * Falls back to a generic layout icon when omitted.
   */
  icon?: AdminIconName;
  /** Short one-line summary shown under the block name (block card subtitle). */
  description?: string;
  /**
   * Presentation variants for this block. All variants share the same `fields`;
   * only the rendered layout differs. The chosen variant is stored on each block
   * row under the reserved `variant` key and passed to the render component as a
   * `variant` prop. Switching variant preserves the author's content.
   */
  variants?: BlockVariant[];
  /** Fields that make up this block's payload. */
  fields: Field[];
}

export type BlocksField = TypedField<"blocks", unknown>;

export interface BlockVariant {
  /** Stable identifier stored on the block row as `variant`. */
  slug: string;
  /** Human-readable label shown in the variant switcher. Defaults to `slug`. */
  label?: string;
  /** Lucide icon name shown beside the variant label. */
  icon?: AdminIconName;
  /** Short one-line summary of what this variant looks like. */
  description?: string;
}

export type BooleanField = TypedField<"boolean", boolean, BooleanFieldAdmin>;

export type BooleanFieldAdmin = {
  /** Boolean presentation style. */
  layout?: "checkbox" | "switch";
};

export type CharacterLimitFieldAdmin = {
  /** Admin-only compatibility alias for `field.maxLength`. Prefer the top-level field property. */
  maxLength?: number;
};

export interface CharacterLimitFieldConfig {
  /** Advisory maximum character count exposed to editors and client tooling. */
  maxLength?: number;
}

export type CollectionAfterChangeHook<TDoc extends object = Record<string, unknown>> = (args: {
  doc: TDoc;
  previousDoc?: TDoc;
  req: HookRequestContext;
  user?: AuthenticatedUser;
  operation: "create" | "update";
  db: DatabaseAdapter;
}) => void | Promise<void>;

export type CollectionAfterDeleteHook<TDoc extends object = Record<string, unknown>> = (args: {
  id: string;
  doc: TDoc;
  req: HookRequestContext;
  user?: AuthenticatedUser;
  db: DatabaseAdapter;
}) => void | Promise<void>;

export type CollectionAfterReadHook<TDoc extends object = Record<string, unknown>> = (args: {
  doc: TDoc;
  req: HookRequestContext;
  user?: AuthenticatedUser;
  db: ReadonlyDatabaseAdapter;
}) => TDoc | Promise<TDoc>;

export type CollectionBeforeChangeHook<TDoc extends object = Record<string, unknown>> = (args: {
  data: Partial<TDoc>;
  doc?: TDoc;
  req: HookRequestContext;
  user?: AuthenticatedUser;
  operation: "create" | "update";
  db: ReadonlyDatabaseAdapter;
}) => Partial<TDoc> | void | Promise<Partial<TDoc> | void>;

export type CollectionBeforeDeleteHook<TDoc extends object = Record<string, unknown>> = (args: {
  id: string;
  doc: TDoc;
  req: HookRequestContext;
  user?: AuthenticatedUser;
  db: ReadonlyDatabaseAdapter;
}) => void | Promise<void>;

export type CollectionBeforeReadHook = (args: {
  req: HookRequestContext;
  query?: Record<string, unknown>;
  user?: AuthenticatedUser;
  db: ReadonlyDatabaseAdapter;
}) => Record<string, unknown> | void | Promise<Record<string, unknown> | void>;

export type DateField = TypedField<"date", string>;

export type DateTimeField = TypedField<"datetime", string>;

export type DynamicOptionItem = string | { label: string; value: unknown };

export interface DynamicOptionsConfig {
  /** Resolver function executed on the server to produce option items. */
  resolve: DynamicOptionsResolver;
  /** Cache duration in seconds for identical resolver calls. */
  cacheTTL?: number;
}

export type DynamicOptionsResolver = (
  args: DynamicOptionsResolverArgs,
) => Promise<DynamicOptionItem[]> | DynamicOptionItem[];

export interface DynamicOptionsResolverArgs {
  /** Database adapter available to server-side option resolvers. */
  db?: DatabaseAdapter;
  /** Authenticated user making the request, if any. */
  user?: AuthenticatedUser;
  /** Current HTTP request context, including query parameters. */
  req: HookRequestContext;
}

export type EmailField = TypedField<"email", string, EmailFieldAdmin> & CharacterLimitFieldConfig;

export type EmailFieldAdmin = CharacterLimitFieldAdmin;

export type Field =
  | TextField
  | TextareaField
  | EmailField
  | UrlField
  | IconField
  | DateField
  | DateTimeField
  | TimeField
  | SelectField
  | RadioField
  | NumberField
  | BooleanField
  | MultiSelectField
  | RelationshipField
  | ImageField
  | RichTextField
  | JsonField
  | ObjectField
  | ArrayField
  | BlocksField
  | JoinField
  | RowField;

export type FieldAdminHooks<TValue> = {
  admin?: {
    hooks?: {
      onChange?: FieldAdminOnChangeHook<TValue>;
    };
  };
};

export type FieldAdminOnChangeHook<TValue = unknown> = (args: FieldAdminOnChangeHookArgs<TValue>) => unknown;

export interface FieldAdminOnChangeHookArgs<TValue = unknown> {
  /** Current field value in the form state. */
  value: TValue;
  /** Current values for sibling fields at the same nesting level. */
  siblingData: Record<string, unknown>;
  /** Current values for the entire form. */
  data: Record<string, unknown>;
  /** Imperative setter for async or derived updates. */
  setValue: (value: unknown) => void;
}

export type FieldAdminOptionsHook = (
  args: FieldAdminOptionsHookArgs,
) => FieldAdminOptionsHookResult | Promise<FieldAdminOptionsHookResult>;

export interface FieldAdminOptionsHookArgs {
  /** Current values for sibling fields at the same nesting level. */
  siblingData: Record<string, unknown>;
  /** Current values for the entire form. */
  data: Record<string, unknown>;
}

export type FieldAdminOptionsHookResult = Array<string | { label: string; value: unknown }>;

export type FieldAfterReadHook<TValue = unknown, TDoc extends object = Record<string, unknown>> = (
  args: FieldAfterReadHookArgs<TValue, TDoc>,
) => unknown;

export interface FieldAfterReadHookArgs<TValue = unknown, TDoc extends object = Record<string, unknown>> {
  /** Raw stored field value before this hook transforms it. */
  value: TValue;
  /** Full document currently being returned to the caller. */
  doc: TDoc;
  /** Authenticated user requesting the document, if any. */
  user?: AuthenticatedUser;
  /** Read-only database adapter for related lookups. */
  db: ReadonlyDatabaseAdapter;
}

export interface FieldBase {
  /** Stored key for this field. Omit only for layout-only fields such as `row` or `join`. */
  name?: string;
  /** Human-readable label shown in the Admin UI. */
  label?: string;
  /** Whether the field must have a value when saving. */
  required?: boolean;
  /** Whether values for this field must be unique across the collection. */
  unique?: boolean;
  /** Default value used when a new document omits this field. */
  defaultValue?: unknown;
  /** Static or dynamic option source for supported selection fields. */
  options?: string[] | { label: string; value: unknown }[] | DynamicOptionsResolver | DynamicOptionsConfig;
  /** Target collection slug for `relationship` fields. */
  relationTo?: string;
  /** Whether the field stores multiple values instead of one. */
  hasMany?: boolean;
  /** Child fields for `object` and `array` field types. */
  fields?: Field[];
  /** Allowed block definitions for a `blocks` field. */
  blocks?: Block[];
  /** Target collection slug for `join` fields. */
  collection?: string;
  /** Back-reference field name on the joined collection. */
  on?: string;
  /** Maximum number of joined documents returned by a `join` field. */
  limit?: number;
  /** Field-level read and update access rules. */
  access?: {
    /** Controls whether this field is returned in API responses. */
    read?: AccessFunction | string;
    /** Controls whether incoming writes may change this field. */
    update?: AccessFunction | string;
  };
  /** Admin-only presentation options for this field. */
  admin?: BaseFieldAdmin;
  /** Previous storage key to migrate from during schema sync. */
  renameTo?: string;
  /** Whether SQL adapters should promote this field into a first-class column. */
  promoted?: boolean;
}

export type FieldBeforeChangeHook<TValue = unknown, TDoc extends object = Record<string, unknown>> = (
  args: FieldBeforeChangeHookArgs<TValue, TDoc>,
) => unknown;

export interface FieldBeforeChangeHookArgs<TValue = unknown, TDoc extends object = Record<string, unknown>> {
  /** Current field value after previous hooks in the chain. */
  value: TValue;
  /** Existing stored document before the write, if this is an update. */
  originalDoc?: TDoc;
  /** Full incoming payload being written. */
  data: Record<string, unknown>;
  /** Authenticated user performing the write, if any. */
  user?: AuthenticatedUser;
  /** Read-only database adapter for related lookups. */
  db: ReadonlyDatabaseAdapter;
}

export type FieldHook<TDoc extends object = Record<string, unknown>, TValue = unknown> = FieldBeforeChangeHook<
  TValue,
  TDoc
>;

export type FieldHooks<TValue> = {
  hooks?: {
    beforeChange?: Array<FieldBeforeChangeHook<TValue>>;
    afterRead?: Array<FieldAfterReadHook<TValue>>;
  };
};

export type FieldType =
  | "text"
  | "textarea"
  | "richText"
  | "number"
  | "boolean"
  | "date"
  | "datetime"
  | "time"
  | "select"
  | "multiSelect"
  | "radio"
  | "relationship"
  | "array"
  | "object"
  | "json"
  | "blocks"
  | "image"
  | "email"
  | "url"
  | "icon"
  | "join"
  | "row";

export type GlobalAfterChangeHook<TDoc extends object = Record<string, unknown>> = (args: {
  doc: TDoc;
  previousDoc?: TDoc;
  req: HookRequestContext;
  user?: AuthenticatedUser;
  operation: "update";
  db: DatabaseAdapter;
}) => void | Promise<void>;

export type GlobalAfterReadHook<TDoc extends object = Record<string, unknown>> = (args: {
  doc: TDoc;
  req: HookRequestContext;
  user?: AuthenticatedUser;
  db: ReadonlyDatabaseAdapter;
}) => TDoc | Promise<TDoc>;

export type GlobalBeforeChangeHook<TDoc extends object = Record<string, unknown>> = (args: {
  data: Partial<TDoc>;
  doc?: TDoc;
  req: HookRequestContext;
  user?: AuthenticatedUser;
  operation: "update";
  db: ReadonlyDatabaseAdapter;
}) => Partial<TDoc> | void | Promise<Partial<TDoc> | void>;

export type GlobalBeforeReadHook = CollectionBeforeReadHook;

export type HookFunction<TDoc extends object = Record<string, unknown>> = (args: {
  data?: Partial<TDoc>;
  doc?: TDoc;
  user?: AuthenticatedUser;
  req?: HookRequestContext;
  operation?: "create" | "update" | "delete";
  db?: DatabaseAdapter;
  [key: string]: unknown;
}) => unknown | Promise<unknown>;

export interface HookRequestContext {
  /** Parsed URL query-string parameters, e.g. `{ page: '2', search: 'hello' }`. */
  query: Record<string, string>;
  /** Incoming HTTP headers, lowercased. */
  headers: Record<string, string>;
  /** The raw Web Standard `Request` object. Useful for streaming or advanced header inspection. */
  raw?: Request;
}

export type IconField = TypedField<"icon", string, IconFieldAdmin> & CharacterLimitFieldConfig;

export type IconFieldAdmin = CharacterLimitFieldAdmin;

export type ImageField = TypedField<"image", string | string[]>;

export type InferDocShape<Fields extends readonly Field[]> = Fields extends readonly []
  ? Record<never, never>
  : Fields extends readonly [infer Head extends Field, ...infer Tail extends readonly Field[]]
    ? InferFieldEntry<Head> & InferDocShape<Tail>
    : Record<string, unknown>;

export type JoinField = TypedField<"join", unknown>;

export type JsonField = TypedField<"json", Record<string, unknown>>;

export type MultiSelectField = TypedField<"multiSelect", string[], MultiSelectFieldAdmin>;

export type MultiSelectFieldAdmin = {
  hooks?: {
    /** Client-side option recalculation for dependent multi-select fields. */
    options?: FieldAdminOptionsHook;
  };
};

export type NumberField = TypedField<"number", number>;

export type ObjectField = TypedField<"object", unknown>;

export type RadioField = TypedField<"radio", string, RadioFieldAdmin>;

export type RadioFieldAdmin = {
  /** Radio group orientation. */
  direction?: "horizontal" | "vertical";
  hooks?: {
    /** Client-side option recalculation for dependent radio groups. */
    options?: FieldAdminOptionsHook;
  };
};

export type RelationshipField = TypedField<"relationship", string | string[]>;

export type RichTextField = TypedField<"richText", Record<string, unknown>>;

export type RowField = TypedField<"row", unknown>;

export type SelectField = TypedField<"select", string, SelectFieldAdmin>;

export type SelectFieldAdmin = {
  /** Select presentation style. */
  layout?: "radio" | "select";
  /** Radio orientation when `layout: 'radio'` is used. */
  direction?: "horizontal" | "vertical";
  hooks?: {
    /** Client-side option recalculation for dependent dropdowns or radios. */
    options?: FieldAdminOptionsHook;
  };
};

export type SystemDocFields = {
  createdAt?: string;
  updatedAt?: string;
  createdBy?: string;
  updatedBy?: string;
};

export type TextareaField = TypedField<"textarea", string, TextareaFieldAdmin> &
  CharacterLimitFieldConfig &
  WordLimitFieldConfig;

export type TextareaFieldAdmin = CharacterLimitFieldAdmin & WordLimitFieldAdmin;

export type TextField = TypedField<"text", string, TextFieldAdmin> & CharacterLimitFieldConfig & WordLimitFieldConfig;

export type TextFieldAdmin = CharacterLimitFieldAdmin & WordLimitFieldAdmin;

export type TimeField = TypedField<"time", string>;

export type TypedField<TType extends FieldType, TValue, TAdminExtra = Record<never, never>> = Omit<FieldBase, "admin"> & {
  type: TType;
  admin?: BaseFieldAdmin & TAdminExtra;
} & FieldHooks<TValue> &
  FieldAdminHooks<TValue>;

export type UploadDocFields = {
  filename: string;
  filesize?: number;
  mimeType: string;
  url: string;
  width?: number;
  height?: number;
  focalPoint?: { x: number; y: number };
  blurhash?: string;
  sizes?: Record<string, { filename?: string; url?: string; width?: number; height?: number }>;
};

export type UrlField = TypedField<"url", string, UrlFieldAdmin> & CharacterLimitFieldConfig;

export type UrlFieldAdmin = CharacterLimitFieldAdmin;

export type WordLimitFieldAdmin = {
  /** Admin-only compatibility alias for `field.maxWords`. Prefer the top-level field property. */
  maxWords?: number;
};

export interface WordLimitFieldConfig {
  /** Advisory maximum word count exposed to editors and client tooling. */
  maxWords?: number;
}