RelationshipFieldInput

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

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:         "full",
    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<TFieldMeta>

Type Parameters

TFieldMeta

TFieldMeta extends object = { }

TCollectionSlug

TCollectionSlug extends CollectionSlug = CollectionSlug

TComponent

TComponent extends ComponentHKT = ComponentHKT

Properties

admin?

optional admin?: FieldAdminConfigInput & RelationshipFieldAdminInput<TCollectionSlug, TComponent>

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

Admin UI configuration for this field.

Overrides

BaseFieldInput.admin

---

collection

collection: object

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

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

slug

slug: TCollectionSlug

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:207

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:194

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:122

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

Default Value

false

---

index?

optional index?: string

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

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"])

Inherited from

BaseFieldInput.index

---

interfaceDescription?

optional interfaceDescription?: string

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

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:185

Display label for the field in the admin form.

Inherited from

BaseFieldInput.label

---

meta?

optional meta?: TFieldMeta

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

Inherited from

BaseFieldInput.meta

---

required?

optional required?: boolean

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

Whether this field is required.

Default: false

Inherited from

BaseFieldInput.required