Checkbox Field

A checkbox custom field stores a single boolean value on a record — checked, unchecked, or unset. Use it for binary flags such as approvals, sign-offs, and confirmations. Checkbox fields are the CHECKBOX value of the CustomFieldType enum. Custom fields are CustomField objects; records are Record objects.

Overview

A checkbox field holds one of three states per record: true (checked), false (unchecked), or null (never set). The value lives on the record, so the same field can be checked on one record and unset on another.

Checkbox fields are scoped to a single workspace by the blue-workspace-id request header — there is no projectId argument on the create input.

Create

Use the createCustomField mutation with type: CHECKBOX. Set the workspace with the blue-workspace-id header.

mutation CreateCheckboxField {
  createCustomField(input: { name: "Reviewed", type: CHECKBOX }) {
    id
    name
    type
  }
}

Add description for help text shown in the app:

mutation CreateCheckboxFieldWithHelp {
  createCustomField(
    input: {
      name: "Customer Approved"
      type: CHECKBOX
      description: "Check this once the customer signs off on the work."
    }
  ) {
    id
    name
    type
    description
  }
}

CreateCustomFieldInput

Response

{
  "data": {
    "createCustomField": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "name": "Reviewed",
      "type": "CHECKBOX"
    }
  }
}

Set a value

Use the setRecordCustomField mutation with the checked argument. The mutation returns Boolean! (true on success) — it does not return the updated record, so do not select subfields on it.

mutation CheckTheBox {
  setRecordCustomField(input: { todoId: "todo_123", customFieldId: "field_123", checked: true })
}

Pass checked: false to uncheck:

mutation UncheckTheBox {
  setRecordCustomField(input: { todoId: "todo_123", customFieldId: "field_123", checked: false })
}

SetRecordCustomFieldInput

Only the fields relevant to a checkbox are shown; the input is shared across all field types.

Response

{
  "data": {
    "setRecordCustomField": true
  }
}

To read the value back after setting it, query the record (see Read a value).

Set a value at record creation

Use the createRecord mutation to set a checkbox while creating the record. Inside customFields, the value is passed as a string (value: "true") — createRecord takes a single value string per field, not the typed checked boolean used by setRecordCustomField.

mutation CreateRecordWithCheckbox {
  createRecord(
    input: {
      title: "Review contract"
      todoListId: "list_123"
      customFields: [{ customFieldId: "field_123", value: "true" }]
    }
  ) {
    id
    title
    customFields {
      name
      type
      checked
    }
  }
}

The elements of Record.customFields are CustomField objects, not a junction type. Select the type-specific value field (checked) directly on the element.

Accepted string values

At record creation the value string is matched exactly and case-sensitively: the string must be "true", "1", or "checked" to produce a checked state. Any other value (including "True", "yes", or "false") is stored as unchecked.

Read a value

Record.customFields returns [CustomField!]! — a list of CustomField objects, one per field set on the record. There is no RecordCustomField wrapper. Select the CustomField fields you need on each element; for a checkbox, checked is the typed boolean read.

query RecordCheckboxValues {
  recordQueries {
    todos(filter: { companyIds: ["company_123"], todoListIds: ["list_123"] }) {
      items {
        id
        title
        customFields {
          name
          type
          checked
          value
        }
      }
    }
  }
}

{
  "data": {
    "recordQueries": {
      "todos": {
        "items": [
          {
            "id": "clm4n8qwx000008l0g4oxdqn7",
            "title": "Review contract",
            "customFields": [
              {
                "name": "Reviewed",
                "type": "CHECKBOX",
                "checked": true,
                "value": { "checked": true }
              }
            ]
          }
        ]
      }
    }
  }
}

Notes

• A checkbox stores one value per record. There is no tri-state beyond true / false / null (unset), and no per-field default — a checkbox is null until first set.
• Toggling a checkbox fires automation triggers: checking it (null/false → true) behaves like a value being added, and unchecking it (true → false) behaves like a value being removed. Build automations that react to these in the Automations API. (Trigger behavior is internal to the resolver and not exposed in the schema.)

Errors

Permissions

Related

• Set custom field values — the shared setRecordCustomField reference across all field types.
• Create a custom field — the full createCustomField reference.
• Single-select field — for more than two mutually exclusive options.
• Custom Fields overview — all field types and concepts.