GSCheckBox

Whether you're building a simple form or a complex data collection system, the GSCheckBox widget offers a user-friendly way for users to select multiple options from a list.

API Reference

This is an illustration of a Themed GSCheckbox widget with default configuration.


    import 'package:gluestack_ui/gluestack_ui.dart';

    GSCheckBox(
      icon: GSCheckBoxIndicator(
        style: GSStyle(margin: EdgeInsets.only(right: $GSSpace.$2)),
        child: const GSCheckBoxIcon(),
      ),
      value: "value 1",
      onChanged: (value) {},
      label: const GSCheckBoxLabel(text: "value1"),
      size: GSCheckBoxSizes.$md,
      isDisabled: false,
      isInvalid: false,
    )

API Reference

Import

To use this component in your project, include the following import statement in your file.

import "package:gluestack_ui/gluestack_ui.dart"

This section provides a comprehensive reference list for the widget parameters, detailing descriptions, properties, types, and default behavior for easy project integration.

GSCheckbox

Contains all InkWell related layout style properties and actions. It inherits all the properties of Flutter's InkWell widget.

Parameters	Type	Default	Description
value	String	-	The value to be used in the checkbox input. This is the value that will be returned on form submission.
onChange	void Function(bool? value)	-	Function called when the state of the checkbox changes.
defaultIsChecked	bool	false	If true, the checkbox will be initially checked.
isChecked	bool	false	When true, the checkbox will be checked. You'll need to pass onChange to update it's value (since it's now controlled).
isDisabled	bool	false	To manually set disable to the checkbox.
isInvalid	bool	false	To manually set invalid to the checkbox.
isReadOnly	bool	false	To manually set read-only to the checkbox.
isHovered	bool	false	To manually set hover to the checkbox.
isFocusVisible	bool	false	To manually set focus visible state to the checkbox.

GSCheckboxIndicator

Contains all indicators related layout style properties and actions. It inherits all the properties of Flutter's Container widget.

GSCheckboxIcon

Contains all Icon related layout style properties and actions. It inherits all the properties of Flutter's Icon widget.

GSCheckboxLabel

Contains all Label related layout style properties and actions. It inherits all the properties of Flutter's Text widget.

Parameters	Type	Default	Description
value	string[]	-	The value of the checkbox group.
onChange	void Function(bool? value)	-	The callback fired when any children Checkbox is checked or unchecked.
isDisabled	bool	false	To manually set disable to the checkbox.
isInvalid	bool	false	To manually set invalid to the checkbox.
isReadOnly	bool	false	To manually set read-only to the checkbox.

Features

Keyboard support for actions.
Support for hover, focus and active states.

Accessibility

We have outlined the various features that ensure the GSCheckbox widget is accessible to all users, including those with disabilities. These features help ensure that your application is inclusive and meets accessibility standards.Adheres to the WAI-ARIA design pattern.

Keyboard

Tab: Moves focus to the next focusable widget.
Shift + Tab: Moves focus to the previous focusable widget.
Space: To check or uncheck focused checkbox.

VoiceOver: When the checkbox is focused, the screen reader will announce it's a checkbox and it's current state (check or uncheck) and it's label.

States

In error state, aria-invalid will be passed to indicate that the radio input has an error, and providing support for an aria-errormessage to describe the error in more detail.
In disabled state, aria-hidden will be passed to make radio input not focusable.
In required state, aria-required will be passed to indicate that the radio input is required.

Parameters

GSCheckbox widget is created using InkWell widget from flutter. It extends all the properties supported by Flutter InkWell and additionally the properties mentioned below.

GSCheckbox

Name	Value	Default
size	lg \| md \| sm	md

Note: These properties are exclusively applicable when utilizing the default configuration of gluestack-ui/config. If you are using a custom theme, these properties may not be available.

Examples

The Examples section provides visual representations of the different variants of the widgets allowing you to quickly and easily determine which one best fits your needs. Simply copy the code and integrate it into your project.

Multiple Checkbox

GSCheckbox provide a mutually exclusive selection mechanism, allowing users to choose a multiple option from a set of related choices.


    import 'package:gluestack_ui/gluestack_ui.dart';

    GSVStack(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        GSCheckBox(
          icon: GSCheckBoxIndicator(
            style: GSStyle(margin: EdgeInsets.only(right: $GSSpace.$2)),
            child: const GSCheckBoxIcon(),
          ),
          value: "Flutter",
          onChanged: (value) {},
          label: const GSCheckBoxLabel(text: "Flutter"),
        ),
        const SizedBox(
          height: 20,
        ),
        GSCheckBox(
          icon: GSCheckBoxIndicator(
            style: GSStyle(margin: EdgeInsets.only(right: $GSSpace.$2)),
            child: const GSCheckBoxIcon(),
          ),
          value: "React",
          onChanged: (value) {},
          label: const GSCheckBoxLabel(text: "React"),
        ),
        const SizedBox(
          height: 20,
        ),
        GSCheckBox(
          icon: GSCheckBoxIndicator(
            style: GSStyle(margin: EdgeInsets.only(right: $GSSpace.$2)),
            child: const GSCheckBoxIcon(),
          ),
          value: "React Native",
          onChanged: (value) {},
          label: const GSCheckBoxLabel(text: "React Native"),
        ),
      ],
    )

Horizontal

A horizontal layout incorporating a checkbox allows for intuitive and space-efficient selection of multiple options within a linear layout.


    import 'package:gluestack_ui/gluestack_ui.dart';

    GSHStack(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        GSCheckBox(
          icon: GSCheckBoxIndicator(
            style: GSStyle(margin: EdgeInsets.only(right: $GSSpace.$2)),
            child: const GSCheckBoxIcon(),
          ),
          value: "Flutter",
          onChanged: (value) {},
          label: const GSCheckBoxLabel(text: "Flutter"),
        ),
        const SizedBox(
          width: 20,
        ),
        GSCheckBox(
          icon: GSCheckBoxIndicator(
            style: GSStyle(margin: EdgeInsets.only(right: $GSSpace.$2)),
            child: const GSCheckBoxIcon(),
          ),
          value: "React",
          onChanged: (value) {},
          label: const GSCheckBoxLabel(text: "React"),
        ),
        const SizedBox(
          width: 20,
        ),
        GSCheckBox(
          icon: GSCheckBoxIndicator(
            style: GSStyle(margin: EdgeInsets.only(right: $GSSpace.$2)),
            child: const GSCheckBoxIcon(),
          ),
          value: "React Native",
          onChanged: (value) {},
          label: const GSCheckBoxLabel(text: "React Native"),
        ),
      ],
    )

With help text

A checkbox widget with help text provides informative guidance alongside selectable options, ensuring clarity and ease of use.


    import 'package:gluestack_ui/gluestack_ui.dart';

    GSVStack(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        GSCheckBox(
          icon: GSCheckBoxIndicator(
            style: GSStyle(
              margin: EdgeInsets.only(
                right: $GSSpace.$4,
              ),
            ),
            child: const GSCheckBoxIcon(),
          ),
          value: "Design",
          onChanged: (value) {},
          label: GSVStack(
            crossAxisAlignment: CrossAxisAlignment.start,
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              GSCheckBoxLabel(text: "Design"),
              GSText(
                text: 'Subscribe to updates from the Design Feed',
              ),
            ],
          ),
        ),
        const SizedBox(
          height: 20,
        ),
        GSCheckBox(
          icon: GSCheckBoxIndicator(
            style: GSStyle(
              margin: EdgeInsets.only(
                right: $GSSpace.$4,
              ),
            ),
            child: const GSCheckBoxIcon(),
          ),
          value: "Marketing",
          onChanged: (value) {},
          label: GSVStack(
            crossAxisAlignment: CrossAxisAlignment.start,
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              GSCheckBoxLabel(text: "Marketing"),
              GSText(
                text: 'Subscribe to updates from the Marketing Feed',
              ),
            ],
          ),
        ),
      ],
    )

Form Control

A checkbox widget integrated with form control enhances the user experience by enabling easy selection and submission of options within a structured input context.


    import 'package:gluestack_ui/gluestack_ui.dart';

    GSVStack(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        const GSHeading(text: 'Sign up for newsletters'),
        const SizedBox(
          height: 10,
        ),
        GSCheckBox(
          icon: GSCheckBoxIndicator(
            style: GSStyle(
              margin: EdgeInsets.only(right: $GSSpace.$2),
            ),
            child: const GSCheckBoxIcon(),
          ),
          value: "Flutter",
          onChanged: (value) {},
          label: const GSCheckBoxLabel(text: "Flutter"),
        ),
        const SizedBox(
          height: 20,
        ),
        GSCheckBox(
          icon: GSCheckBoxIndicator(
            style: GSStyle(
              margin: EdgeInsets.only(right: $GSSpace.$2),
            ),
            child: const GSCheckBoxIcon(),
          ),
          value: "React",
          onChanged: (value) {},
          label: const GSCheckBoxLabel(text: "React"),
        ),
        const SizedBox(
          height: 20,
        ),
        GSCheckBox(
          icon: GSCheckBoxIndicator(
            style: GSStyle(
              margin: EdgeInsets.only(right: $GSSpace.$2),
            ),
            child: const GSCheckBoxIcon(),
          ),
          value: "React Native",
          onChanged: (value) {},
          label: const GSCheckBoxLabel(text: "React Native"),
        ),
        const SizedBox(
          height: 10,
        ),
        const GSText(text: 'Subscribe to newsletters for updates'),
      ],
    )

Controlled

A controlled widget architecture incorporates a checkbox widget, allowing for precise management of its state and behavior through explicit control mechanisms.


    import 'package:gluestack_ui/gluestack_ui.dart';
    GSVStack(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        GSCheckBox(
          isChecked: true,
          icon: GSCheckBoxIndicator(
            style: GSStyle(
              margin: EdgeInsets.only(right: $GSSpace.$2),
            ),
            child: const GSCheckBoxIcon(),
          ),
          value: "Flutter",
          onChanged: (value) {},
          label: const GSCheckBoxLabel(text: "Flutter"),
        ),
        const SizedBox(
          height: 20,
        ),
        GSCheckBox(
          icon: GSCheckBoxIndicator(
            style: GSStyle(
              margin: EdgeInsets.only(right: $GSSpace.$2),
            ),
            child: const GSCheckBoxIcon(),
          ),
          value: "React",
          onChanged: (value) {},
          label: const GSCheckBoxLabel(text: "React"),
        ),
        const SizedBox(
          height: 20,
        ),
        GSCheckBox(
          icon: GSCheckBoxIndicator(
            style: GSStyle(
              margin: EdgeInsets.only(right: $GSSpace.$2),
            ),
            child: const GSCheckBoxIcon(),
          ),
          isChecked: true,
          value: "React Native",
          onChanged: (value) {},
          label: const GSCheckBoxLabel(text: "React Native"),
        ),
      ],
    )

Uncontrolled

An uncontrolled widget utilizes a checkbox widget, providing a simpler implementation where the checkbox state is managed internally, without explicit control from external sources.


    import 'package:gluestack_ui/gluestack_ui.dart';

    GSVStack(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        GSCheckBox(
          icon: GSCheckBoxIndicator(
            style: GSStyle(
              margin: EdgeInsets.only(right: $GSSpace.$2),
            ),
            child: const GSCheckBoxIcon(),
          ),
          value: "Appartments",
          onChanged: (value) {},
          label: const GSCheckBoxLabel(text: "Appartments"),
        ),
        const SizedBox(
          height: 20,
        ),
        GSCheckBox(
          icon: GSCheckBoxIndicator(
            style: GSStyle(
              margin: EdgeInsets.only(right: $GSSpace.$2),
            ),
            child: const GSCheckBoxIcon(),
          ),
          value: "Residents",
          onChanged: (value) {},
          label: const GSCheckBoxLabel(text: "Residents"),
        ),
      ],
    )

Checkbox group

The checkbox group widget allows users to group checkbox and display them in a horizontal or vertical row for better visual representation and functionality.


    import 'package:gluestack_ui/gluestack_ui.dart';

    GSVStack(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        GSCheckBox(
          isDisabled: true,
          icon: GSCheckBoxIndicator(
            style: GSStyle(
              margin: EdgeInsets.only(right: $GSSpace.$2),
            ),
            child: const GSCheckBoxIcon(),
          ),
          value: "Disabled",
          onChanged: (value) {},
          label: const GSCheckBoxLabel(text: "Disabled"),
        ),
        const SizedBox(
          height: 20,
        ),
        GSCheckBox(
          icon: GSCheckBoxIndicator(
            style: GSStyle(
              margin: EdgeInsets.only(right: $GSSpace.$2),
            ),
            child: const GSCheckBoxIcon(),
          ),
          value: "Active",
          onChanged: (value) {},
          label: const GSCheckBoxLabel(text: "Active"),
        ),
      ],
    )