Fields

Field methods target /api/collections/{slug}/fields routes. They require an API key with the admin ability.

const noma = createClient({ projectId, apiKey })

Field names in the API use kebab-case. Payloads follow the REST API; see Key Concepts for field types and Create a Field for the HTTP body shape.

`fields.create`

Add a field to a collection.

await noma.fields.create("blog-posts", {
  type: "longtext",
  label: "Excerpt",
  name: "excerpt",
  options: {
    repeatable: false,
    hideInContentList: false,
    hiddenInAPI: false,
  },
  validations: {
    required: { status: false, message: "" },
  },
})

Argument	Type	Description
`collectionSlug`	`string`	Collection slug.
`payload`	`Record<string, unknown>`	Field definition (`name`, `type`, `options`, validations, and so on).

`fields.update`

Update an existing field. The second argument must be the field UUID (the value returned as uuid on each field). The API route is PUT /api/collections/{slug}/fields/{uuid} and does not look up fields by numeric database id.

The Content API validates a full field document on PUT: type, label, and name are always required. Optional keys include description, placeholder, options, validations, and parent_field_id.

To change whether values are required when saving entries, update validations.required (status + message), not options.

// Typical pattern: load the collection (or current field), merge, then PUT.
const collection = (await noma.collections.get("blog-posts")) as {
  fields?: Array<Record<string, unknown>>
}
const field = collection.fields?.find((f) => f.name === "excerpt")
if (!field) throw new Error("Field not found")
 
await noma.fields.update("blog-posts", String(field.uuid), {
  type: field.type,
  label: field.label,
  name: field.name,
  description: field.description ?? null,
  placeholder: field.placeholder ?? null,
  options: field.options ?? {},
  validations: {
    ...(field.validations as Record<string, unknown>),
    required: { status: true, message: "Excerpt is required" },
  },
  parent_field_id: field.parent_field_id ?? null,
})

Argument	Type	Description
`collectionSlug`	`string`	Collection slug.
`fieldId`	`number \| string`	Field UUID as returned by the API (string). The path segment is matched against `uuid`.
`payload`	`Record<string, unknown>`	Body for `PUT`. Must include `type`, `label`, and `name` per API rules.

`fields.delete`

Remove a field from a collection.

await noma.fields.delete("blog-posts", fieldUuid)

Removing a field can delete stored values for that field on existing entries. Plan migrations carefully.

`fields.reorder`

Change the order of fields in the content editor.

import type { FieldsReorderPayload } from "@nomacms/js-sdk"
 
const payload: FieldsReorderPayload = {
  fields: [
    { uuid: "field-uuid-1", order: 0 },
    { uuid: "field-uuid-2", order: 1 },
  ],
}
 
await noma.fields.reorder("blog-posts", payload)

Field	Description
`fields`	Array of `{ uuid, order }`.

Create a Field - POST /api/collections/{slug}/fields
Update a Field - PUT .../fields/{uuid}
Delete a Field - DELETE .../fields/{uuid}
Reorder Fields - POST .../fields/reorder
Collections - Create collections and inline fields in one step.
Key Concepts - Field types and options overview.

Fields

Fields

Related

Search documentation