checkbox field

A checkbox() field stores a boolean true/false value. It is ideal for feature flags, published states, opt-in toggles, visibility flags, and any setting that has exactly two states.

Config options

| Option | Type | Default | Description | |--------|------|---------|-------------| | label | string | "" | Display label in the admin panel. Inferred from the field key by defineCollection when left empty. | | required | boolean | false | When false, the field is wrapped in v.optional(…) in the schema. | | defaultValue | boolean | false | Pre-filled value shown in the admin form when creating a new document. | | index | string \| { name, additionalFields?, draftStatus? } | — | Convex index name, or the object form for a compound index. | | description | string | — | Helper text shown below the field input. | | admin.hidden | boolean | false | Hides the field from the admin edit form entirely. | | admin.readOnly | boolean | false | Renders the checkbox as non-interactive. | | admin.position | "main" \| "sidebar" | "main" | Column in the admin edit layout where this field appears. | | admin.width | string | "100%" | CSS width of the field in the edit form (e.g. "50%", "240px"). Meaningful as a child of row(); below a narrow form column every field renders full width regardless. | | admin.cellAlignment | "left" \| "center" \| "right" | "left" | Horizontal alignment of the value in the list-view table cell. | | admin.placeholder | string | — | Placeholder text (not typically used for checkboxes). | | admin.description | string | — | Helper text displayed below the field input. | | admin.condition | (props: { data, siblingData }) => boolean | — | Shows the field only while this returns true. A throwing condition counts as met. Hidden fields skip required/validate on the server too. See the Conditional fields & masks guide. |

Schema output

// Optional (required: false — default)
featured: v.optional(v.boolean())

// Required, checked by default
published: v.boolean()

// With a database index
archived: v.boolean(),
.index("by_archived", ["archived"])

Usage

import { defineCollection, checkbox, text } from "@vexcms/core";

const posts = defineCollection({
  slug: "posts",
  fields: {
    // Minimal — label inferred from key ("Published")
    published: checkbox(),

    // Checked by default, shown in the sidebar
    featured: checkbox({ defaultValue: true, admin: { position: "sidebar", width: "50%" } }),

    // Indexed flag for fast admin queries
    archived: checkbox({ index: "by_archived" }),
  },
});

Admin UI

The checkbox field renders as a toggle switch (or native checkbox) in the edit form. In the list-view table, the value is displayed as a checked/unchecked indicator. Checkboxes are commonly placed in the sidebar with width: "50%" so two flags can sit side-by-side.