BlocksFieldInput

Defined in: packages/core/src/fields/blocks/types.ts:215

Configuration input for a blocks() field.

Blocks fields store an ordered, heterogeneous list of typed objects. Each item carries blockType (which block definition it matches), id (stable UUID), blockName (user-editable label), plus the fields from that block’s definition.

Defaults applied by blocks():

{
  type:         "blocks",
  label:        "",    // inferred from field key by defineCollection
  required:     false,
  defaultValue: [],
  labels:       { singular: "block", plural: "blocks" },
  admin: {
    hidden: false, readOnly: false, position: "main", width: "100%",
    cellAlignment: "left",
  }
}

Examples

body: blocks({
  label:  "Body",
  blocks: [headingBlock, paragraphBlock],
})

// Named union alias + min/max constraints
body: blocks({
  label:         "Body",
  interfaceName: "PageBlock",
  blocks:        [headingBlock, paragraphBlock],
  min:           1,
  max:           20,
  labels:        { singular: "section", plural: "sections" },
})

See

• BlocksField for the resolved output type
• blocks for the config function that produces this type

Extends

• Omit<BaseFieldInput<TCollectionSlug, TFieldKey, TFieldMeta>, "admin">

Type Parameters

TCollectionSlug

TCollectionSlug extends VexResourceSlug = VexResourceSlug

TFieldKey

TFieldKey extends string = never

TFieldMeta

TFieldMeta extends object = { }

Properties

admin?

optional admin?: BlocksFieldAdminInput<TCollectionSlug>

Defined in: packages/core/src/fields/blocks/types.ts:220

---

blocks

blocks: BlockConfig<TFieldMeta>[]

Defined in: packages/core/src/fields/blocks/types.ts:222

Block type definitions that are allowed in this field.

---

defaultValue?

optional defaultValue?: Record<string, unknown>[]

Defined in: packages/core/src/fields/blocks/types.ts:249

Pre-filled value when creating a new document. Defaults to [].

Overrides

BaseFieldInput.defaultValue

---

description?

optional description?: string

Defined in: packages/core/src/fields/baseTypes.ts:516

Semantic description of the field. Used in three places:

1. Helper text rendered below the field input in the admin form UI.
2. As the Zod .meta({ description }) value for form validation.
3. As the JSDoc comment on the generated document interface property.

To write a separate JSDoc comment, use interfaceDescription in addition.

Inherited from

BaseFieldInput.description

---

index?

optional index?: FieldIndexConfigInput<TCollectionSlug, TFieldKey>

Defined in: packages/core/src/fields/baseTypes.ts:545

Create a database index on this field. The string value becomes the index name in Convex.

Example

slug: { type: "text", index: "by_slug", required: true }
// Generates: .index("by_slug", ["slug"])

author: { type: "relationship", index: { name: "by_author_status", additionalFields: ["status"] } }
// Generates: .index("by_author_status", ["author", "status"])

Inherited from

Omit.index

---

interfaceDescription?

optional interfaceDescription?: string

Defined in: packages/core/src/fields/baseTypes.ts:518

The JSDoc comment on the generated document interface property

Inherited from

BaseFieldInput.interfaceDescription

---

interfaceName?

optional interfaceName?: string

Defined in: packages/core/src/fields/blocks/types.ts:229

Optional TypeScript union alias name.

When set, emits export type PageBlock = HeadingBlock | ParagraphBlock and the collection interface uses PageBlock[] instead of the inline union.

---

label?

optional label?: string

Defined in: packages/core/src/fields/baseTypes.ts:507

Display label for the field in the admin form.

Inherited from

BaseFieldInput.label

---

labels?

optional labels?: object

Defined in: packages/core/src/fields/blocks/types.ts:247

Singular/plural display labels used in the admin UI. Defaults to { singular: "block", plural: "blocks" }.

plural

plural: string

singular

singular: string

---

max?

optional max?: FieldLimitInput

Defined in: packages/core/src/fields/blocks/types.ts:245

Maximum number of block items.

Enforced by the Zod inputSchema. When the max is reached, the “Add” button is disabled in the admin UI.

See

FieldLimitInput

---

meta?

optional meta?: TFieldMeta

Defined in: packages/core/src/fields/baseTypes.ts:546

Inherited from

Omit.meta

---

min?

optional min?: FieldLimitInput

Defined in: packages/core/src/fields/blocks/types.ts:237

Minimum number of block items.

Enforced by the Zod inputSchema (form validation), not the Convex schema. Does not affect the generated vex.schema.ts.

See

FieldLimitInput

---

required?

optional required?: boolean

Defined in: packages/core/src/fields/baseTypes.ts:524

Whether this field is required.

Default: false

Inherited from

BaseFieldInput.required

Methods

validate()?

optional validate(props): void | Promise<void>

Defined in: packages/core/src/fields/blocks/types.ts:251

Server-only async validation with value typed as GenericBlock[].

Parameters

props

FieldValidateProps<TCollectionSlug, GenericBlock[]>

Returns

void | Promise<void>

See

FieldValidate

Overrides

Omit.validate