The checkbox column represents a simple true or false value on a board. The API allows you to read, filter, update, and clear the checkbox column.

Read a checkbox column

You can query the checkbox column using the column_values object that enables you to return column-specific subfields by sending a fragment in your query. Values for the checkbox column are of the CheckboxValue type.

query {
  items(
    ids: [
      1234567890
      9876543210
    ]
	) {
    column_values {
      ... on CheckboxValue {
        checked
        updated_at
      }
    }
  }
}

import { ApiClient } from "@mondaydotcomorg/api";
const mondayApiClient = new ApiClient({ token: myToken });

const query = `query($itemIds: [ID!]) { items (ids:$itemIds) { column_values { value ...on CheckboxValue { checked updated_at } } } }`;
const variables = {
  itemIds: [9571351485, 9572374902],
};

const response = await mondayApiClient.request(query, variables);

Fields

Field	Description
checked `Boolean`	Returns `true` if the column is checked.
column `Column!`	The column the value belongs to.
id `ID!`	The column's unique identifier.
text `String`	The column's value as text. This field will return `""` if the column has an empty value.
type `ColumnType!`	The column's type.
updated_at `Date`	The column's last updated date.
value `JSON`	The column's JSON-formatted raw value.

Filter a checkbox column

Using the items_page object, you can easily filter a board's items by specific columns or column values. The table below contains the checkbox column's supported operators and compare values.

Operators	Compare values
`is_empty`	`[]`
`is_not_empty`	`[]`

Examples

The following example returns all items on the specified board that have an unchecked checkbox column.

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "check"
            compare_value: []
            operator: is_empty
          }
        ]
      }
    ) {
      items {
        id
        name
      }
    }
  }
}

import { ApiClient } from "@mondaydotcomorg/api";
const mondayApiClient = new ApiClient({ token: myToken });

const query = `query ($board_id: [ID!], $column_id: ID!, $operator: ItemsQueryRuleOperator!, $compare_value:CompareValue!) { boards (ids: $board_id) { items_page (query_params: {rules: [{column_id: $column_id, compare_value: $compare_value, operator:$operator}]}) { items { id name } } } }`;
const variables = {
  board_id: 9571351437,
  column_id: "boolean_mksrnay",
  compare_value: [null],
  operator: "is_empty",
};
const response = await mondayApiClient.request(query, variables);

Update a checkbox column

You can update a checkbox column using the change_multiple_column_values mutation and passing a JSON string in the column_values argument. Simple string updates are not supported.

JSON

To check the box, send {"checked" : "true"} in the column_values argument.

mutation {
  change_multiple_column_values(
    item_id: 1234567890
    board_id: 9876543210
    column_values: "{\"checkbox\":{\"checked\":\"true\"}}"
  ) {
    id
  }
}

import { ApiClient } from "@mondaydotcomorg/api";
const mondayApiClient = new ApiClient({ token: myToken });

const query = `mutation ($myBoardId:ID!, $myItemId:ID!, $myColumnValues:JSON!) { change_multiple_column_values(item_id:$myItemId, board_id:$myBoardId, column_values: $myColumnValues) { id } }`;
const variables = {
  myBoardId: 9571351437,
  myItemId: 9571351485,
  myColumnValues: JSON.stringify({
    boolean_mksrnay: {checked: true} // "boolean_mksrnay" is the column ID
  }),
};
const response = await mondayApiClient.request(query, variables);

Clear a checkbox column

You can also clear (uncheck) a checkbox column using the change_multiple_column_values mutation and passing null in the column_values argument.

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"checkbox\": null}"
  ) {
    id
  }
}

import { ApiClient } from "@mondaydotcomorg/api";
const mondayApiClient = new ApiClient({ token: myToken });

const query = `mutation ($myBoardId:ID!, $myItemId:ID!, $myColumnValues:JSON!) { change_multiple_column_values(item_id:$myItemId, board_id:$myBoardId, column_values: $myColumnValues) { id } }`;
const variables = {
  myBoardId: 9571351437,
  myItemId: 9571351485,
  myColumnValues: JSON.stringify({checkbox_id123: null}) // "checkbox_id123" is the column ID
};

const response = await mondayApiClient.request(query, variables);