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.

Choose a version:

Checkbox

The checkbox component provides a clear way for customers to make selections, such as agreeing to terms, enabling settings, or choosing multiple items from a list. Use checkbox to create binary on/off controls or multi-select interfaces where customers can select any combination of options.

Checkboxes support labels, help text, error states, and an indeterminate state for grouped selections. For settings that take effect immediately, use Switch instead.

Support

Targets (25)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the Checkbox component.

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 Opt in to marketingOpt in to marketing

Use checkbox to let customers make a binary selection like subscribing to updates. This example shows a basic marketing opt-in checkbox.

Opt in to marketing

Opt in to marketing

import {

reactExtension,

Checkbox,

} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(

'customer-account.page.render',

() => <Extension />,

);

function Extension() {

return (

Save this information for next time

</Checkbox>

);

}

import {extension, Checkbox} from '@shopify/ui-extensions/customer-account';

export default extension('customer-account.page.render', (root) => {

const checkbox = root.createComponent(

Checkbox,

{id: 'checkbox', name: 'checkbox'},

'Save this information for next time',

);

root.appendChild(checkbox);

});

React

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

export default reactExtension(
  'customer-account.page.render',
  () => <Extension />,
);

function Extension() {
  return (
    <Checkbox id="checkbox" name="checkbox">
      Save this information for next time
    </Checkbox>
  );
}

JS

import {extension, Checkbox} from '@shopify/ui-extensions/customer-account';

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

  root.appendChild(checkbox);
});

Anchor to Embed links in a checkbox labelEmbed links in a checkbox label

To provide customers with additional information or references, include link components within checkbox labels. This gives customers easy access to relevant content like terms of service or privacy policies.

Embed links in a checkbox label

A checkbox with an embedded link in the label text

Embed links in a checkbox label

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{' '}

terms and conditions

</Link>{' '}

and{' '}

</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);

);

React

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>
  );
};

JavaScript

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 customer is agreeing to or selecting.
Pre-check thoughtfully: Only use defaultChecked for options that benefit the customer. Don't pre-check options that add cost.
Show validation errors inline: Use the error property to display messages directly below the checkbox for required fields.
Pair with forms: Use checkboxes inside a Form when selections need to be submitted together with other input.

Anchor to LimitationsLimitations

The required attribute doesn't trigger automatic validation.

Was this page helpful?