RelationshipFieldInput

Defined in: packages/core/src/fields/relationship/types.ts:103

Configuration input for a relationship() field.

Stores Convex Id references to documents in another registered collection. The Convex schema always uses v.array(v.id("slug")) regardless of hasMany. hasMany is a UI-only hint — false shows a single-selection picker, true shows a multi-selection picker. TCollectionSlug is inferred from the collection option — after running vex generate, invalid slugs are a compile-time error.

Defaults applied by relationship():

{
  type:     "relationship",
  label:    "",    // inferred from the field key by defineCollection
  required: false,
  hasMany:  false, // single-select picker in the admin UI; schema is always v.array(v.id())
  admin: {
    hidden:        false,
    readOnly:      false,
    position:      "main",
    width: "100%",
    cellAlignment: "left",
  }
}

@typeParam TCollectionSlug - The target collection slug. Inferred from `collection`.
  Defaults to `CollectionSlug` (the full union after `vex generate`).

@example
```ts
// Single reference
author: relationship({ collection: { slug: "authors" } })

// Multi-reference
tags: relationship({ collection: { slug: "tags" }, hasMany: true })

@see {@link RelationshipField} for the resolved output type @see {@link relationship} for the config function @see {@link CollectionSlug} for the valid slug union

Extends

• BaseFieldInput<TCollectionSlug, TFieldKey, TFieldMeta>

Type Parameters

TCollectionSlug

TCollectionSlug extends VexResourceSlug = VexResourceSlug

TFieldKey

TFieldKey extends string = never

TFieldMeta

TFieldMeta extends object = { }

TTargetSlug

TTargetSlug extends CollectionSlug = CollectionSlug

TComponent

TComponent extends ComponentHKT = ComponentHKT

Properties

admin?

optional admin?: RelationshipFieldAdminInput<TCollectionSlug, TTargetSlug, TComponent>

Defined in: packages/core/src/fields/relationship/types.ts:125

Admin UI configuration for this field.

Overrides

BaseFieldInput.admin

---

collection

collection: object

Defined in: packages/core/src/fields/relationship/types.ts:111

Target collection reference. The slug must match a registered collection in defineConfig.

slug

slug: TTargetSlug

The slug of the collection this field links to. Must be a registered collection slug.

---

defaultValue?

optional defaultValue?: unknown

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

Pre-filled value shown in the admin form when creating a new field. Does not apply to database values

Inherited from

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

---

hasMany?

optional hasMany?: boolean

Defined in: packages/core/src/fields/relationship/types.ts:120

Whether this field stores multiple references. false stores a single Id, true stores Id[].

Default Value

false

---

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

BaseFieldInput.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

---

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

---

max?

optional max?: FieldLimitInput

Defined in: packages/core/src/fields/relationship/types.ts:124

Maximum number of related documents allowed.

See

FieldLimitInput

---

meta?

optional meta?: TFieldMeta

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

Inherited from

BaseFieldInput.meta

---

min?

optional min?: FieldLimitInput

Defined in: packages/core/src/fields/relationship/types.ts:122

Minimum number of related documents required, once a value is supplied.

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/relationship/types.ts:127

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

Parameters

props

FieldValidateProps<TCollectionSlug, string[]>

Returns

void | Promise<void>

See

FieldValidate

Overrides

BaseFieldInput.validate