Skip to content
Gx
GitHub

Checkbox

A single boolean control with a label.

<checkbox.Checkbox name="terms">Accept the terms</checkbox.Checkbox>

Installation

Run the command in the app module.

Terminal
gx add checkbox

The command also installs icons.

The command writes these files.

File Path in the app
Checkbox.gx ui/checkbox/Checkbox.gx
Checkbox.fixtures.go ui/checkbox/Checkbox.fixtures.go
styles.go ui/checkbox/styles.go

Install icons first.

Copy each file to its path in the app. Change each import of a registry package to the path of that package in the app.

ui/checkbox/Checkbox.gx
package checkbox

import "github.com/alternayte/gx/registry/icons"

props {
  // Name is the name attribute of the input. The form sends the value under this name.
  Name     string = ""
  // Value is the value the form sends when the checkbox is checked.
  Value    string = "on"
  // Checked renders the checkbox checked.
  Checked  bool = false
  // Disabled stops the user from changing the checkbox and dims it.
  Disabled bool = false
  // Invalid sets aria-invalid on the input and shows the error style.
  Invalid  bool = false
  // Class adds classes to the root element, the label.
  Class    string = ""
  // Children is the checkbox label. A nil value renders the box alone.
  Children gx.Node = nil
  // Attrs adds HTML attributes to the root element, the label.
  Attrs    gx.Attrs = nil
}

<label class={gx.Cx("flex items-center gap-2 text-sm leading-none font-medium select-none", p.Class)} {...p.Attrs}>
  <input type="checkbox" name={p.Name} value={p.Value} checked={p.Checked} disabled={p.Disabled} aria-invalid={p.invalid()} class="peer sr-only" />
  <span aria-hidden="true" class="grid size-4 shrink-0 place-content-center rounded-[4px] border border-input text-transparent shadow-xs transition-shadow outline-none peer-focus-visible:border-ring peer-focus-visible:ring-[3px] peer-focus-visible:ring-ring/50 peer-disabled:cursor-not-allowed peer-disabled:opacity-50 peer-aria-invalid:border-destructive peer-aria-invalid:ring-destructive/20 peer-checked:border-primary peer-checked:bg-primary peer-checked:peer-focus-visible:border-primary peer-checked:text-primary-foreground dark:bg-input/30 dark:peer-aria-invalid:ring-destructive/40 dark:peer-checked:bg-primary motion-reduce:transition-none">
    <icons.Check class="size-3.5" />
  </span>
  if p.Children != nil {
    <span class="peer-disabled:cursor-not-allowed peer-disabled:opacity-50">{p.Children}</span>
  }
</label>
ui/checkbox/Checkbox.fixtures.go
package checkbox

import "github.com/alternayte/gx"

var CheckboxFixtures = gx.Fixtures[CheckboxProps]{
	"Unchecked":       {Name: "terms", Children: gx.Text("Accept the terms")},
	"Checked":         {Name: "terms", Checked: true, Children: gx.Text("Accept the terms")},
	"Disabled":        {Name: "terms", Disabled: true, Children: gx.Text("Disabled")},
	"DisabledChecked": {Name: "terms", Checked: true, Disabled: true, Children: gx.Text("Disabled")},
	"Invalid":         {Name: "terms", Invalid: true, Children: gx.Text("Accept the terms")},
}
ui/checkbox/styles.go
package checkbox

// invalid returns the aria-invalid value of the input.
func (p CheckboxProps) invalid() string {
	if p.Invalid {
		return "true"
	}
	return "false"
}

The theme must define these tokens: --input, --primary, --primary-foreground, --ring, --destructive.

Usage

<checkbox.Checkbox name="terms" checked={p.Accepted}>Accept the terms</checkbox.Checkbox>
<checkbox.Checkbox name="terms" invalid={p.TermsMissing}>Accept the terms</checkbox.Checkbox>

The checkbox is a native input behind a styled box. Disabled and Invalid set the state of the input.

Examples

Unchecked

<checkbox.Checkbox name="terms">Accept the terms</checkbox.Checkbox>

Checked

<checkbox.Checkbox name="terms" checked>Accept the terms</checkbox.Checkbox>

Disabled

<checkbox.Checkbox name="terms" disabled>Disabled</checkbox.Checkbox>

Disabled checked

<checkbox.Checkbox name="terms" checked disabled>Disabled</checkbox.Checkbox>

Invalid

<checkbox.Checkbox name="terms" invalid>Accept the terms</checkbox.Checkbox>

API reference

A tag sets a prop by its name with a lower-case first letter: Class is class.

checkbox.Checkbox

Prop Type Default Description
Name string "" Name is the name attribute of the input. The form sends the value under this name.
Value string "on" Value is the value the form sends when the checkbox is checked.
Checked bool false Checked renders the checkbox checked.
Disabled bool false Disabled stops the user from changing the checkbox and dims it.
Invalid bool false Invalid sets aria-invalid on the input and shows the error style.
Class string "" Class adds classes to the root element, the label.
Children gx.Node nil Children is the checkbox label. A nil value renders the box alone.
Attrs gx.Attrs nil Attrs adds HTML attributes to the root element, the label.

Do and do not

Do

  • Use one checkbox per independent choice.
  • Wrap the control and its label in the component.

Don't

  • Do not use a checkbox for a mutually exclusive choice. Use a radio group.
  • Do not use a checkbox for an immediate action. Use a switch.

Keyboard

Key Action
Tab Moves focus to the checkbox.
Space Toggles the value.