arkyn

v3.0.1-beta.72

Checkbox

The Checkbox component is used to create interactive checkbox inputs with customizable styling and validation support. It's ideal for optional selections, agreements, settings, and multiple choice lists.

tsx

import { Checkbox } from "@arkyn/components";

Basic usage

Basic usage of an checkbox requires a name property.

tsx

<Checkbox name="basic-checkbox" />

Sizes

The available sizes are sm, md and lg, offering different dimensions to suit your layout needs.

tsx

<Checkbox name="checkbox-sm" label="Small checkbox" size="sm" />
<Checkbox name="checkbox-md" label="Medium checkbox" size="md" />
<Checkbox name="checkbox-lg" label="Large checkbox" size="lg" />

Checkboxes with labels

Labels help identify the purpose of the checkbox and make the clickable area larger.

tsx

<Checkbox name="terms" label="I accept the terms and conditions" />

Orientation

Checkbox options can be arranged in a single line or in columns, depending on available space and design preference.

Horizontal

tsx

<Checkbox name="option1" label="Option 1" orientation="horizontal" />
<Checkbox name="option2" label="Option 2" orientation="horizontal" />

Horizontal reverse

The "reverse horizontal" orientation is default, it is not necessary to inform it.

tsx

<Checkbox name="option1" label="Option 1"  />
<Checkbox name="option2" label="Option 2"  />

Vertical

tsx

<Checkbox name="option1" label="Option 1" orientation="vertical" />
<Checkbox name="option2" label="Option 2" orientation="vertical" />

Checkbox states

The component supports different states, such as disabled and with different default checked values.

Default checked state

tsx

<Checkbox name="remember-me" label="Remember me" defaultChecked={true} />

Disabled checkbox

The disabled state prevents any user interaction with the field and prevents data from being submitted through a form.

tsx

<Checkbox
  name="disabled-unchecked"
  label="Disabled option (unchecked)"
  disabled
/>
<Checkbox
  name="disabled-checked"
  label="Disabled option (checked)"
  disabled
  defaultChecked
/>

Validation and errors

The component integrates with form validation systems and can display error messages. If an error message is provided via the errorMessage property, it will take precedence over messages from the form provider.
Customizable Forms
For forms, it is recommended to use the FormProvider which offers native integration with all form tools.

tsx

<Checkbox
  name="invalid-terms"
  label="I accept the terms and conditions"
  errorMessage="You must accept the terms"
  showAsterisk
/>

Custom values

Use the value property to define a specific value when the checkbox is checked.

tsx

<Checkbox
  name="subscription-basic"
  label="Basic Plan"
  value="basic"
  onCheck={(value) => alert("Selected plan:" + value)}
/>

onCheck callback

The onCheck callback provides the checkbox value when checked or an empty string when unchecked:

tsx

function handleCheckboxChange(value: string) {
  // value: string - value defined in the value prop or "checked" if not specified
  // For unchecked checkbox, value will be an empty string ""


  if (value) {
    alert("Checkbox checked with value:" + value); // "subscribeNewsletter"
  } else {
    alert("Checkbox unchecked"); // ""
  }
}


<Checkbox
  name="newsletter"
  label="Receive newsletter"
  value="subscribeNewsletter"
  onCheck={handleCheckboxChange}
/>;

Controlled checkbox

tsx

const [isPremium, setIsPremium] = useState(true);


<Checkbox
  name="controlled-premium"
  label="Premium features"
  checked={isPremium}
  onCheck={(value) => setIsPremium(!!value)}
/>;

Properties

name - string (required) Field name for form manipulation and identification
label - string Label text to be displayed next to the checkbox
errorMessage - string Error message to display below the checkbox
showAsterisk - boolean Whether to display an asterisk in the label for required fields
size - "sm" | "md" | "lg" (default: "md") Checkbox size variant
orientation - "horizontal" | "horizontalReverse" | "vertical" (default: "horizontal") Orientation of the checkbox and label
value - string (default: "checked") Optional value to be used when the checkbox is checked
checked - boolean Controlled checked state of the checkbox
defaultChecked - boolean (default: false) Default checked state for uncontrolled use
onCheck - (value: string) => void Callback function called when the checkbox state changes, receives the value or empty string
Other properties
All other standard HTML properties of <button> are also supported, except type, name, defaultValue, value, onChange, onSelect and onClick which are controlled by the component.

Notes

  • Use checked for controlled state and defaultChecked for uncontrolled
  • The onCheck callback receives string (value or "") instead of boolean
On this page