Skip to main content
Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Checkbox

Use the Checkbox component to give buyers a single binary option, such as signing up for marketing, or agreeing to terms and conditions.

Support
Targets (50)

Supported targets

Anchor to CheckboxPropsCheckboxProps

Anchor to accessibilityLabel
accessibilityLabel
string

A label used for users of assistive technologies. When set, any children supplied to this component will not be announced to screen reader users.

Anchor to checked
checked
boolean

Whether the checkbox is active.

Anchor to disabled
disabled
boolean

Whether the checkbox is disabled, preventing any user interaction.

Anchor to error
error
string

An error message displayed below the field to indicate validation problems. When set, the field is styled with error indicators.

Anchor to id
id
string

A unique identifier for the field. When no id is set, a globally unique value will be used instead.

Anchor to name
name
string

An identifier for the field that is unique within the nearest containing Form component.

Anchor to onChange
onChange
(value: boolean) => void

A callback fired when the checkbox value changes. This callback is called with a boolean indicating whether the checkbox should now be active or inactive. This component is controlled, so you must store this value in state and reflect it back in the checked or value props.

Anchor to toggles
toggles
string

The ID of the component whose visibility will be toggled when this component is activated. Use this to show or hide related content like a disclosure panel.

Anchor to value
value
boolean

Whether the checkbox is active. This prop is an alias for checked, and can be useful in form libraries that provide a normalized API for dealing with both boolean and string values. If both value and checked are set, checked takes precedence.

Anchor to ExamplesExamples

Anchor to Basic CheckboxBasic Checkbox

Basic Checkbox

Example

Basic Checkbox

import {
reactExtension,
Checkbox,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
'purchase.checkout.block.render',
() => <Extension />,
);

function Extension() {
return (
<Checkbox id="checkbox" name="checkbox">
Save this information for next time
</Checkbox>
);
}
import {extension, Checkbox} from '@shopify/ui-extensions/checkout';

export default extension('purchase.checkout.block.render', (root) => {
const checkbox = root.createComponent(
Checkbox,
{id: 'checkbox', name: 'checkbox'},
'Save this information for next time',
);

root.appendChild(checkbox);
});

Anchor to Embedding links in checkbox componentsEmbedding links in checkbox components

To provide buyers with additional information or references, couple the Checkbox component with link components seamlessly. This can be done by including links as part of the checkbox label. This will provide an easy way to access relevant content that buyers may need.

Embedding links in checkbox components

To provide buyers with additional information or references, couple the Checkbox component with link components seamlessly. This can be done by including links as part of the checkbox label. This will provide an easy way to access relevant content that buyers may need.

Embedding links in checkbox components

import {
reactExtension,
Checkbox,
Link,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
'purchase.checkout.block.render',
() => <CheckBoxLinks />,
);

export const CheckBoxLinks = () => {
return (
<Checkbox
id="checkbox1"
name="checkboxchoices"
>
I agree to the{' '}
<Link to="https://www.shopify.com">
terms and conditions
</Link>{' '}
and{' '}
<Link to="https://www.shopify.com">
privacy policy
</Link>{' '}
of the store related to pricing, payment,
shipping, returns, and liability set forth
by Ride Sports
</Checkbox>
);
};
import {
extension,
Checkbox,
Link,
} from '@shopify/ui-extensions/checkout';

export default extension(
'purchase.checkout.block.render',
(root) => {
const checkbox = root.createComponent(
Checkbox,
{
id: 'checkbox1',
name: 'checkboxchoices',
},
[
' I agree to the ',
root.createComponent(
Link,
{to: 'https://www.shopify.com'},
'terms and conditions',
),
' and ',
root.createComponent(
Link,
{to: 'https://www.shopify.com'},
'privacy policy',
),
' of the store related to pricing, payment, shipping, returns, and liability set forth by Ride Sports.',
],
);

root.appendChild(checkbox);
},
);

Anchor to Best practicesBest practices

  • Write descriptive labels: Use clear, specific text that explains what the buyer is agreeing to or selecting.
  • Pre-check thoughtfully: Only use defaultChecked for options that benefit the buyer, such as marketing opt-in. Don't pre-check options that add cost.
  • Show validation errors inline: Use the error property to display messages directly below the Checkbox component for required fields.
  • Use switch for instant effects: If a selection takes effect immediately without a form submission, use the Switch component instead.
  • Pair with forms: Use the Checkbox component inside the Form component when selections need to be submitted together with other input.

Anchor to LimitationsLimitations

  • Automatic required validation isn't built in. Use the error property to communicate validation problems.
  • When accessibilityLabel is set, child label content isn't announced to screen readers in the same way as the default labeling pattern. See the property documentation for details.
Was this page helpful?