Form Components

Checkbox

The <Checkbox> component adds an interactive tick box to a PDF form. It stores one of two string states, and the reader toggles between them.

New to forms? Start with the Forms guide.

Props

Prop	Type	Default	Description
`name`	`string`	`''`	Field identifier. This is the key the value is exported under.
`checked`	`boolean`	`false`	Whether the box starts in its on state.
`onState`	`string`	`'Yes'`	Value exported when the box is ticked.
`offState`	`string`	`'Off'`	Value exported when the box is not ticked.
`xMark`	`boolean`	`false`	Draw a cross instead of a tick when checked.
`backgroundColor`	`string`	—	Interior colour of the box.
`borderColor`	`string`	—	Outline colour of the box.
`value`	`string \| number`	—	The field's current value. Usually set through checked instead.
`defaultValue`	`string \| number`	—	The value the field reverts to when the form is reset.
`required`	`boolean`	`false`	Marks the field as mandatory before the form can be submitted.
`readOnly`	`boolean`	`false`	Displays the state but prevents the reader from toggling it.
`noExport`	`boolean`	`false`	Excludes the field from the exported form data.
`style`	`Style \| Style[]`	—	Size and position of the box.

Usage

vue

<template>
  <Document>
    <Page size="A4" :style="{ padding: 40 }">
      <View :style="{ flexDirection: 'row', alignItems: 'center', gap: 6 }">
        <Checkbox
          name="terms"
          checked
          :style="{ width: 14, height: 14 }"
        />
        <Text :style="{ fontSize: 10 }">
          I accept the terms and conditions
        </Text>
      </View>
    </Page>
  </Document>
</template>

A <Checkbox> has no intrinsic size. Give it an explicit width and height or it will be invisible. Square dimensions look best in most readers.

Appearance

The tick and cross glyphs come from the ZapfDingbats font, which vue-pdf embeds automatically the first time a checkbox is rendered.

vue

<template>
  <Document>
    <Page size="A4" :style="{ padding: 40 }">
      <!-- Tick mark (default) -->
      <Checkbox name="tick" checked :style="{ width: 14, height: 14 }" />

      <!-- Cross mark -->
      <Checkbox name="cross" checked x-mark :style="{ width: 14, height: 14 }" />

      <!-- Styled interior and outline -->
      <Checkbox
        name="styled"
        background-color="#f1f5f9"
        border-color="#0f172a"
        :style="{ width: 14, height: 14 }"
      />
    </Page>
  </Document>
</template>

Custom States

By default a checkbox exports Yes or Off. Override onState and offState when the system consuming the form expects specific values:

vue

<template>
  <Document>
    <Page size="A4" :style="{ padding: 40 }">
      <Checkbox
        name="newsletter"
        checked
        on-state="Subscribed"
        off-state="Unsubscribed"
        :style="{ width: 14, height: 14 }"
      />
    </Page>
  </Document>
</template>

Use the same onState and offState for every checkbox in a document. Readers differ in how they handle a form whose checkboxes use inconsistent state names, and mixed naming is a common source of boxes that appear blank or refuse to toggle.

Grouping

Wrap checkboxes in a FieldSet to namespace them under a shared prefix.