SelectableBox

A box that has selection states. It can be used as an alternative to a radio button or checkbox set.

The SelectableBox can contain any kind of content as long as it is not clickable. In other words, there should be no clickable targets distinct from selection.

Basic Usage

As Checkbox

Show editable code example

Any Paragon component or export may be added to the code example.

() => {
  const type = 'checkbox';
  const allCheeseOptions = ['swiss', 'cheddar', 'pepperjack'];
  const [checkedCheeses, { add, remove, set, clear }] = useCheckboxSetValues(['swiss']);

  const handleChange = e => {
    e.target.checked ? add(e.target.value) : remove(e.target.value);
  };
  
  const isInvalid = () => checkedCheeses.includes('swiss');
  const isExtraSmall = useMediaQuery({ maxWidth: breakpoints.extraSmall.maxWidth });
  
  return (
    <div className="bg-light-200 p-3">
      <SelectableBox.Set
        value={checkedCheeses}
        type={type}
        onChange={handleChange}
        name="cheeses"
        columns={isExtraSmall ? 1 : 2}
        ariaLabel="cheese selection"
      >
        <SelectableBox value="swiss" type={type} aria-label="swiss checkbox">
          <div>
            <h3>It is my first SelectableBox</h3>
            <p>Swiss</p>
          </div>
        </SelectableBox>
        <SelectableBox value="cheddar" inputHidden={false} type={type} aria-label="cheddar checkbox">
          Cheddar
        </SelectableBox>
        <SelectableBox
          value="pepperjack"
          inputHidden={false}
          type={type}
          isInvalid={isInvalid()}
          aria-label="pepperjack checkbox"
        >
          <h3>Pepperjack</h3>
        </SelectableBox>
      </SelectableBox.Set>
    </div>
  );
}

() => {
  const type = 'checkbox';
  const allCheeseOptions = ['swiss', 'cheddar', 'pepperjack'];
  const [checkedCheeses, { add, remove, set, clear }] = useCheckboxSetValues(['swiss']);

  const handleChange = e => {
    e.target.checked ? add(e.target.value) : remove(e.target.value);
  };
  
  const isInvalid = () => checkedCheeses.includes('swiss');
  const isExtraSmall = useMediaQuery({ maxWidth: breakpoints.extraSmall.maxWidth });
  
  return (
    <div className="bg-light-200 p-3">
      <SelectableBox.Set
        value={checkedCheeses}
        type={type}
        onChange={handleChange}
        name="cheeses"
        columns={isExtraSmall ? 1 : 2}
        ariaLabel="cheese selection"
      >
        <SelectableBox value="swiss" type={type} aria-label="swiss checkbox">
          <div>
            <h3>It is my first SelectableBox</h3>
            <p>Swiss</p>
          </div>
        </SelectableBox>
        <SelectableBox value="cheddar" inputHidden={false} type={type} aria-label="cheddar checkbox">
          Cheddar
        </SelectableBox>
        <SelectableBox
          value="pepperjack"
          inputHidden={false}
          type={type}
          isInvalid={isInvalid()}
          aria-label="pepperjack checkbox"
        >
          <h3>Pepperjack</h3>
        </SelectableBox>
      </SelectableBox.Set>
    </div>
  );
}

As Radio

Show editable code example

Any Paragon component or export may be added to the code example.

() => {
  const type = 'radio';
  const [value, setValue] = useState('green');
  const handleChange = e => setValue(e.target.value);
  const isExtraSmall = useMediaQuery({ maxWidth: breakpoints.extraSmall.maxWidth });

  return (
    <SelectableBox.Set
      type={type}
      value={value}
      onChange={handleChange}
      name="colors"
      columns={isExtraSmall ? 1 : 3}
      ariaLabel="color selection"
    >
      <SelectableBox value="red" type={type} aria-label="red checkbox">
        <div>
          <h3>It is Red color</h3>
          <p>Select me</p>
        </div>
      </SelectableBox>
      <SelectableBox value="green" inputHidden={false} type={type} aria-label="green-checkbox">
        <h3>Green</h3>
        <p>Leaves and grass</p>
      </SelectableBox>
      <SelectableBox value="blue" inputHidden={false} type={type} aria-label="blue checkbox">
        <h3>Blue</h3>
        <p>The sky</p>
      </SelectableBox>
    </SelectableBox.Set>
  );
}

() => {
  const type = 'radio';
  const [value, setValue] = useState('green');
  const handleChange = e => setValue(e.target.value);
  const isExtraSmall = useMediaQuery({ maxWidth: breakpoints.extraSmall.maxWidth });

  return (
    <SelectableBox.Set
      type={type}
      value={value}
      onChange={handleChange}
      name="colors"
      columns={isExtraSmall ? 1 : 3}
      ariaLabel="color selection"
    >
      <SelectableBox value="red" type={type} aria-label="red checkbox">
        <div>
          <h3>It is Red color</h3>
          <p>Select me</p>
        </div>
      </SelectableBox>
      <SelectableBox value="green" inputHidden={false} type={type} aria-label="green-checkbox">
        <h3>Green</h3>
        <p>Leaves and grass</p>
      </SelectableBox>
      <SelectableBox value="blue" inputHidden={false} type={type} aria-label="blue checkbox">
        <h3>Blue</h3>
        <p>The sky</p>
      </SelectableBox>
    </SelectableBox.Set>
  );
}

As Checkbox

As Checkbox with isIndeterminate

Show editable code example

Any Paragon component or export may be added to the code example.

() => {
  const type = 'checkbox';
  const allCheeseOptions = ['swiss', 'cheddar', 'pepperjack'];
  const [checkedCheeses, { add, remove, set, clear }] = useCheckboxSetValues(['swiss']);

  const allChecked = allCheeseOptions.every(value => checkedCheeses.includes(value));
  const someChecked = allCheeseOptions.some(value => checkedCheeses.includes(value));
  const isIndeterminate = someChecked && !allChecked;
  const isExtraSmall = useMediaQuery({ maxWidth: breakpoints.small.maxWidth });

  const handleChange = e => {
    e.target.checked ? add(e.target.value) : remove(e.target.value);
  };

  const handleCheckAllChange = ({ checked }) => {
    checked ? set(allCheeseOptions) : clear();
  };

  return (
    <>
      <div className="mb-3">
        <SelectableBox
          checked={allChecked}
          isIndeterminate={isIndeterminate}
          onClick={handleCheckAllChange}
          inputHidden={false}
          type={type}
          aria-label="all options checkbox"
        >
          All the cheese
        </SelectableBox>
      </div>
      <SelectableBox.Set
        value={checkedCheeses}
        type={type}
        onChange={handleChange}
        name="cheeses"
        columns={isExtraSmall ? 1 : 3}
        ariaLabel="cheese selection"
      >
        <SelectableBox value="swiss" type={type} aria-label="swiss checkbox">
          <div>
            <h3>It is my first SelectableBox</h3>
            <p>Swiss</p>
          </div>
        </SelectableBox>
        <SelectableBox value="cheddar" inputHidden={false} type={type} aria-label="cheddar checkbox">
          Cheddar
        </SelectableBox>
        <SelectableBox value="pepperjack" inputHidden={false} type={type} aria-label="pepperjack checkbox">
          <h3>Pepperjack</h3>
        </SelectableBox>
      </SelectableBox.Set>
    </>
  );
}

() => {
  const type = 'checkbox';
  const allCheeseOptions = ['swiss', 'cheddar', 'pepperjack'];
  const [checkedCheeses, { add, remove, set, clear }] = useCheckboxSetValues(['swiss']);

  const allChecked = allCheeseOptions.every(value => checkedCheeses.includes(value));
  const someChecked = allCheeseOptions.some(value => checkedCheeses.includes(value));
  const isIndeterminate = someChecked && !allChecked;
  const isExtraSmall = useMediaQuery({ maxWidth: breakpoints.small.maxWidth });

  const handleChange = e => {
    e.target.checked ? add(e.target.value) : remove(e.target.value);
  };

  const handleCheckAllChange = ({ checked }) => {
    checked ? set(allCheeseOptions) : clear();
  };

  return (
    <>
      <div className="mb-3">
        <SelectableBox
          checked={allChecked}
          isIndeterminate={isIndeterminate}
          onClick={handleCheckAllChange}
          inputHidden={false}
          type={type}
          aria-label="all options checkbox"
        >
          All the cheese
        </SelectableBox>
      </div>
      <SelectableBox.Set
        value={checkedCheeses}
        type={type}
        onChange={handleChange}
        name="cheeses"
        columns={isExtraSmall ? 1 : 3}
        ariaLabel="cheese selection"
      >
        <SelectableBox value="swiss" type={type} aria-label="swiss checkbox">
          <div>
            <h3>It is my first SelectableBox</h3>
            <p>Swiss</p>
          </div>
        </SelectableBox>
        <SelectableBox value="cheddar" inputHidden={false} type={type} aria-label="cheddar checkbox">
          Cheddar
        </SelectableBox>
        <SelectableBox value="pepperjack" inputHidden={false} type={type} aria-label="pepperjack checkbox">
          <h3>Pepperjack</h3>
        </SelectableBox>
      </SelectableBox.Set>
    </>
  );
}

As Checkbox with ariaLabelledby

Show editable code example

Any Paragon component or export may be added to the code example.

() => {
  const type = 'checkbox';
  const allCheeseOptions = ['swiss', 'cheddar', 'pepperjack'];
  const [checkedCheeses, { add, remove, set, clear }] = useCheckboxSetValues(['swiss']);

  const handleChange = e => {
    e.target.checked ? add(e.target.value) : remove(e.target.value);
  };
  
  const isExtraSmall = useMediaQuery({ maxWidth: breakpoints.extraSmall.maxWidth });
  
  return (
    <div className="bg-light-200 p-3">
      <h3 id="cheese selection" className="mb-4">
        Select your favorite cheese
      </h3>
      <SelectableBox.Set
        value={checkedCheeses}
        type={type}
        onChange={handleChange}
        name="cheeses"
        columns={isExtraSmall ? 1 : 3}
        ariaLabelledby="cheese selection"
      >
        <SelectableBox value="swiss" inputHidden={false} type={type} aria-label="swiss checkbox">
          <h3>
            Swiss
          </h3>
        </SelectableBox>
        <SelectableBox value="cheddar" inputHidden={false} type={type} aria-label="cheddar checkbox">
          <h3>
            Cheddar
          </h3>
        </SelectableBox>
        <SelectableBox value="pepperjack" inputHidden={false} type={type} aria-label="pepperjack checkbox">
          <h3>
            Pepperjack
          </h3>
        </SelectableBox>
      </SelectableBox.Set>
    </div>
  );
}

() => {
  const type = 'checkbox';
  const allCheeseOptions = ['swiss', 'cheddar', 'pepperjack'];
  const [checkedCheeses, { add, remove, set, clear }] = useCheckboxSetValues(['swiss']);

  const handleChange = e => {
    e.target.checked ? add(e.target.value) : remove(e.target.value);
  };
  
  const isExtraSmall = useMediaQuery({ maxWidth: breakpoints.extraSmall.maxWidth });
  
  return (
    <div className="bg-light-200 p-3">
      <h3 id="cheese selection" className="mb-4">
        Select your favorite cheese
      </h3>
      <SelectableBox.Set
        value={checkedCheeses}
        type={type}
        onChange={handleChange}
        name="cheeses"
        columns={isExtraSmall ? 1 : 3}
        ariaLabelledby="cheese selection"
      >
        <SelectableBox value="swiss" inputHidden={false} type={type} aria-label="swiss checkbox">
          <h3>
            Swiss
          </h3>
        </SelectableBox>
        <SelectableBox value="cheddar" inputHidden={false} type={type} aria-label="cheddar checkbox">
          <h3>
            Cheddar
          </h3>
        </SelectableBox>
        <SelectableBox value="pepperjack" inputHidden={false} type={type} aria-label="pepperjack checkbox">
          <h3>
            Pepperjack
          </h3>
        </SelectableBox>
      </SelectableBox.Set>
    </div>
  );
}

Theme Variables (SCSS)#

$selectable-box-padding:                    1rem !default;
$selectable-box-border-radius:              .25rem !default;
$selectable-box-space:                      .75rem !default;
$min-cols-number:                           1 !default;
$max-cols-number:                           12 !default;

Props API#

SelectableBox Props API

children node Required
Content of the SelectableBox.
value string | number
A value that is passed to the input tag.
checked bool
Controls whether SelectableBox is checked.
Defaultfalse
type enum'radio' | 'checkbox'
Indicates the input type: checkbox or radio.
Default'radio'
onClick func
Function that is called when the SelectableBox is clicked.
Default() => {}
onFocus func
Function that is called when the SelectableBox is focused.
Default() => {}
inputHidden bool
Controls display of the input (checkbox or radio button) on the SelectableBox.
Defaulttrue
isIndeterminate bool
Indicates a state for the 'checkbox' type when SelectableBox is neither checked nor unchecked.
Defaultfalse
isInvalid bool
Adds errors styles to the SelectableBox.
Defaultfalse
className string
A class that is appended to the base element.

SelectableBoxSet Props API

name string Required
Specifies a name for the group of SelectableBox'es.
children node
Content of the SelectableBoxSet.
onChange func
A function that receives event of the clicked SelectableBox and can be used to handle the value change.
Default() => {}
value string | number | array
Indicates selected SelectableBox'es.
defaultValue string | number
Specifies default values for the SelectableBox'es.
type enum'radio' | 'checkbox'
Indicates the input type: checkbox or radio.
Default'radio'
columns number
Specifies number of SelectableBox'es in a row.
Class that is responsible for the columns number: pgn__selectable_box-set--{columns}. Max number of columns: 12.
Default2
className string
A class that is be appended to the base element.
ariaLabelledby string
The ID of the label for the SelectableBoxSet.
An accessible label must be provided to the SelectableBoxSet.
ariaLabel requiredWhenNot(PropTypes.string, 'ariaLabelledby')
A label for the SelectableBoxSet.
If not using ariaLabelledby, then ariaLabel must be provided

Usage Insights#

SelectableBox

Project Name	Paragon Version	Instance Count
frontend-app-course-authoring	20.35.1	1
frontend-app-enterprise-public-catalog	20.29.0	3
frontend-app-learner-portal-enterprise	20.45.1	1
frontend-app-learner-record	20.45.0	1
frontend-lib-content-components	20.45.0	2

SelectableBoxSet

Project Name	Paragon Version	Instance Count
frontend-app-course-authoring	20.35.1	1
frontend-app-enterprise-public-catalog	20.29.0	1
frontend-app-learner-portal-enterprise	20.45.1	1
frontend-app-learner-record	20.45.0	1
frontend-lib-content-components	20.45.0	2

Leave feedback

Paragon Design System

Theme

SelectableBox

Basic Usage

As Radio

As Checkbox

Theme Variables (SCSS)#

Props API#

Usage Insights#

SelectableBox

SelectableBoxSet

All components (A-Z)

Theme

SelectableBox

Basic Usage#

As Radio#

As Checkbox#

Theme Variables (SCSS)#

Props API#

Usage Insights#

SelectableBox

SelectableBoxSet

All components (A-Z)

Basic Usage

As Radio

As Checkbox