> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overflow.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkbox

> A boolean input for merchant-defined opt-ins and consent rows.

The `checkbox` custom element renders a native `<input type="checkbox">` with an aligned label. Use it for consent rows, opt-ins, or any boolean toggle in the payment form.

## Factory

```typescript theme={null}
overflow.checkbox(options: CustomCheckboxElementOptions): CustomCheckboxElement
```

## Example

```javascript theme={null}
const agree = overflow.checkbox({
  name: 'agree',
  label: 'I agree to the terms',
  required: true,
});

agree.on('onChange', ({ value }) => console.log(value));
agree.mount('#agree');
```

## Options

| Key                                                 | Type                                 | Default                                                      | Notes                                             |
| --------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------- |
| `elementType`                                       | `'checkbox'`                         | required                                                     | Discriminant when configured inside Checkout.     |
| `name`                                              | `string`                             | required                                                     | Unique per `Overflow` instance.                   |
| `label`                                             | `string`                             | required                                                     | Renders as the input's label.                     |
| `defaultValue`                                      | `boolean`                            | `false`                                                      | Pass `true` to render pre-checked.                |
| `mode`                                              | `'inline' \| 'stacked'`              | `'inline'`                                                   | Layout variant. See below.                        |
| `required`                                          | `boolean`                            | `false`                                                      | Unchecked box surfaces a `required` `FieldError`. |
| `validate`                                          | `(value: boolean) => string \| null` | none                                                         | Overrides the built-in `required` check.          |
| `disabled`, `readOnly`, `id`, `ariaLabel`, `locale` | shared                               | see [reference](/payment-elements/elements/custom/reference) |                                                   |

### `mode`

* `'inline'` (default) renders the checkbox on the leading edge with the label to its right. The entire row is clickable. Best for consent rows where the label reads as a sentence.
* `'stacked'` renders the label above the checkbox, matching the layout of other custom inputs. Use this when the checkbox needs to align with text inputs in a form grid.

### `required` semantics

`required: true` means "must be checked", matching the native HTML `<input type="checkbox" required>` semantic. Use it for terms-and-conditions style hard consents. An unchecked box surfaces a `FieldError` with `code: 'required'` and `submit()` rejects with `code: 'validation_failed'`. Leave `required` unset for optional opt-ins and read the boolean off the change event.

### `complete` semantics

* `required: true` and unchecked → `complete: false` with a `required` error.
* `required: true` and checked → `complete: true`.
* No `required`, no `validate` → `complete: true` regardless of state.
* With `validate` → `complete: true` only when the callback returns `null`.

## Value

```typescript theme={null}
type CustomCheckboxValue = boolean;
```

A checkbox always has a state. The emitted value is always `boolean`, never `null`. The change envelope, the submit envelope, and the imperative `element.value` getter all return the same boolean.

## Inside Checkout

```javascript theme={null}
overflow.checkout({
  paymentMethods: ['card'],
  customElements: {
    agree: {
      elementType: 'checkbox',
      label: 'I agree to the terms',
      required: true,
    },
  },
});
```

## See also

* [Custom elements introduction](/payment-elements/elements/custom/introduction)
* [Custom reference](/payment-elements/elements/custom/reference)