Skip to content
Gx
GitHub

Switch

A control for an immediate on or off setting.

<switches.Switch name="wifi" label="Wifi" />

Installation

Run the command in the app module.

Terminal
gx add switch

The command writes these files.

File Path in the app
Switch.gx ui/switch/Switch.gx
Switch.fixtures.go ui/switch/Switch.fixtures.go
styles.go ui/switch/styles.go

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/switch/Switch.gx
package switches

props {
  // Size sets the size of the track and the thumb: Md or Sm.
  Size     Size = Md
  // Name is the form field name.
  Name     string = ""
  // Label is the accessible name of the switch.
  Label    string = ""
  // Value is the value the form submits when the switch is on.
  Value    string = "on"
  // Checked sets the switch on for the first render.
  Checked  bool = false
  // Disabled disables the switch.
  Disabled bool = false
  // Class adds classes to the root element.
  Class    string = ""
  // Attrs adds HTML attributes to the root element.
  Attrs    gx.Attrs = nil
}

<label data-size={p.size()} class={gx.Cx("inline-flex shrink-0 items-center rounded-full border border-transparent bg-input shadow-xs transition-all outline-none has-[:checked]:bg-primary has-[:focus-visible]:border-ring has-[:focus-visible]:ring-[3px] has-[:focus-visible]:ring-ring/50 has-[:disabled]:cursor-not-allowed has-[:disabled]:opacity-50 dark:bg-input/80 dark:has-[:checked]:bg-primary motion-reduce:transition-none", trackClass[p.size()], p.Class)} {...p.Attrs}>
  <input type="checkbox" role="switch" name={p.Name} aria-label={p.Label} value={p.Value} checked={p.Checked} disabled={p.Disabled} class="peer sr-only" />
  <span class={gx.Cx("pointer-events-none block translate-x-0 rounded-full bg-background ring-0 transition-transform peer-checked:translate-x-[calc(100%-2px)] dark:bg-foreground dark:peer-checked:bg-primary-foreground motion-reduce:transition-none", thumbClass[p.size()])}></span>
</label>
ui/switch/Switch.fixtures.go
package switches

import "github.com/alternayte/gx"

var SwitchFixtures = gx.Fixtures[SwitchProps]{
	"Off":      {Name: "wifi", Label: "Wifi"},
	"On":       {Name: "wifi", Label: "Wifi", Checked: true},
	"Disabled": {Name: "wifi", Label: "Wifi", Disabled: true},
	"Small":    {Name: "wifi", Label: "Wifi", Size: Sm},
	"SmallOn":  {Name: "wifi", Label: "Wifi", Size: Sm, Checked: true},
}
ui/switch/styles.go
package switches

import "github.com/alternayte/gx"

// Size is the size of a switch.
type Size string

// The sizes of switches.Switch.
const (
	Md Size = "default"
	Sm Size = "sm"
)

var trackClass = gx.Enum[Size]{
	Md: "h-[1.15rem] w-8",
	Sm: "h-3.5 w-6",
}

var thumbClass = gx.Enum[Size]{
	Md: "size-4",
	Sm: "size-3",
}

// size returns the size of one switch; a zero value is Md.
func (p SwitchProps) size() Size {
	if p.Size == "" {
		return Md
	}
	return p.Size
}

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

Usage

<switches.Switch name="wifi" label="Wifi" checked={p.Wifi} />
<switches.Switch name="sync" label="Sync" size={switches.Sm} />

The switch is a styled checkbox with the switch role. The sizes are switches.Md and switches.Sm. Disabled disables the checkbox.

Examples

Off

<switches.Switch name="wifi" label="Wifi" />

On

<switches.Switch name="wifi" label="Wifi" checked />

Disabled

<switches.Switch name="wifi" label="Wifi" disabled />

Small

<switches.Switch name="wifi" label="Wifi" size={switches.Sm} />

Small on

<switches.Switch name="wifi" label="Wifi" size={switches.Sm} checked />

API reference

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

switches.Switch

Prop Type Default Description
Size Size Md Size sets the size of the track and the thumb: Md or Sm.
Name string "" Name is the form field name.
Label string "" Label is the accessible name of the switch.
Value string "on" Value is the value the form submits when the switch is on.
Checked bool false Checked sets the switch on for the first render.
Disabled bool false Disabled disables the switch.
Class string "" Class adds classes to the root element.
Attrs gx.Attrs nil Attrs adds HTML attributes to the root element.

Do and do not

Do

  • Use a switch when the change takes effect at once.
  • Pair the switch with a visible label.

Don't

  • Do not use a switch inside a form that needs a submit button.
  • Do not use a switch for a multi-choice setting.

Keyboard

Key Action
Tab Moves focus to the switch.
Space Toggles the switch.