UI-licious Documentation

Appearance

Checking checkboxes and radio buttons ​

Checkboxes and radio buttons allow users to make choices in forms.

To check a checkbox or radio button, use I.select(). If the option is already checked, I.select() does nothing. While I.click() can also toggle checkboxes and radio buttons, it naively toggles the element and may uncheck an already selected option. As such, we recommend using I.select() whenever your goal is to ensure selection.

Checking an option ​

To select a simple checkbox, you can use the visible label or value of the option:
Demo: Simple Checkbox
UI
HTML
js
I.select("I agree")

Similarly for a radio button:
Demo: Simple Radio Button
UI
HTML
js
I.select("Red")

You can also use CSS or XPath selectors to target the option:

js
// using CSS
I.select("#agree-to-terms")

// using XPath
I.select("//input[value='r']")

TIP

We strongly recommend using visible labels instead of CSS or XPath selectors. Tests written this way remain more readable and resilient to UI changes.

Checking an option in a group ​

If there are multiple options with the same label, we recommend specifying both the list and the option to target using I.select(list, option).


	Door color

	
	
	






	Frame color
Demo: Radio Button Group
UI
HTML
js
I.select("Door color", "Red")
I.select("Frame color", "Blue")

How UI-licious identifies options to select ​

To identify an option, UI-licious evaluates the following:

  • the visible label of the option
  • descriptive attributes, e.g. aria-label, title
  • the value of the option
  • surrounding text

To identify an option group, UI-licious evaluates the following:

  • name attribute
  • surrounding text

Hidden and custom-styled checkboxes ​

Many modern websites and CSS frameworks (like Tailwind or Bootstrap) hide the native <input type="checkbox"> (using opacity: 0, display: none, or offscreen positioning) and style an associated <label> or pseudo-element instead:
Demo: Hidden Checkbox with Styled Label
UI
HTML

When interacting with hidden checkboxes, keep this crucial rule in mind:

  • Target the visible label text (Recommended): I.select("Subscribe to newsletter") succeeds because UI-licious automatically locates the visible <label> paired with the hidden <input> and clicks the label.
  • Do not target the hidden input directly: I.select("#subscribe-news") fails because hidden DOM elements cannot receive click interactions.
js
// ✅ WORKS: Targets the visible label
I.select("Subscribe to newsletter")

// ❌ FAILS: Cannot click on hidden input directly
I.select("#subscribe-news")

Purely custom toggle components ​

If your application uses custom widgets that do not include an underlying <input> element at all (for instance, a <div> or <span> styled to look like a toggle switch), I.select cannot detect the form state. Use I.click instead:

js
I.click("I consent")

Unchecking checkboxes ​

Use I.deselect to uncheck a checkbox.

js
I.deselect("Subscribe to newsletter")

If the checkbox is already unchecked, nothing happens.

Verifying selection ​

You can assert that a checkbox or radio button is checked using the I.selected command:

js
// fails if "I agree" checkbox is unchecked
I.selected("I agree")

// fails if "Red" option in "Door color" group is unchecked
I.selected("Door color", "Red")

Inversely, you can assert that a checkbox or radio button is unchecked using the I.deselected command:

js
// fails if "I agree" checkbox is checked
I.deselected("I agree")

// fails if "Red" option in "Door color" group is checked
I.deselected("Door color", "Red")