AbstractChoiceList
API reference › HTML › Form › AbstractChoiceList
2 subclasses
Provides shared immutable rendering behavior for checkbox and radio lists.
Renders every ChoiceItem as an atomic input paired with a <label>, wrapped in a container element that
carries the list attributes. Selection is configured on the list through checked(), never on the items.
CheckboxList for the checkbox implementation.
RadioList for the radio implementation.
Properties
Section titled “Properties”| Property | Type | Description | Defined by |
|---|---|---|---|
$attributes protected | mixed[] | HTML attributes array used by the implementing class. Default: []. | UIAwesome\ |
$content protected | string | Content string assigned to the element. Default: ''. | UIAwesome\ |
Methods
Section titled “Methods”| Method | Description | Defined by |
|---|---|---|
__construct() final | Initializes a new tag instance. | UIAwesome\ |
__toString() | Returns the rendered tag string. | UIAwesome\ |
accesskey() | Sets the accesskey attribute. | UIAwesome\ |
addAriaAttribute() | Sets an aria-* attribute. | UIAwesome\ |
addAttribute() | Adds or updates a single HTML attribute for the element. | UIAwesome\ |
addDataAttribute() | Sets a data-* attribute. | UIAwesome\ |
addEvent() | Sets an on* event attribute. | UIAwesome\ |
ariaAttributes() | Sets multiple aria-* attributes. | UIAwesome\ |
attributes() | Adds or updates multiple HTML attributes for the element. | UIAwesome\ |
autofocus() | Sets the autofocus attribute. | UIAwesome\ |
begin() final | Starts begin/end rendering for this instance. | UIAwesome\ |
checked() | Sets the values determining which items are checked. | AbstractChoiceList |
class() | Sets the class attribute. | UIAwesome\ |
clearContent() | Clears encoded and raw content without changing other component state. | UIAwesome\ |
config() | Applies application-scoped config recipes to this tag. | UIAwesome\ |
content() | Appends encoded content. | UIAwesome\ |
contentEditable() | Sets the contenteditable attribute. | UIAwesome\ |
dataAttributes() | Sets multiple data-* attributes. | UIAwesome\ |
dir() | Sets the dir attribute. | UIAwesome\ |
draggable() | Sets the draggable attribute. | UIAwesome\ |
enclosedByLabel() | Configures whether every item input and its text are enclosed by the item label. | AbstractChoiceList |
end() static final | Ends the most recent begin/end rendering block for the current class. | UIAwesome\ |
events() | Sets multiple on* event attributes. | UIAwesome\ |
getAttribute() | Returns the value of a single HTML attribute. | UIAwesome\ |
getAttributes() | Returns the array of HTML attributes for the element. | UIAwesome\ |
getContent() | Returns the content assigned to the element. | UIAwesome\ |
hidden() | Sets the hidden attribute. | UIAwesome\ |
html() | Appends trusted raw HTML content without encoding or sanitizing it. | UIAwesome\ |
id() | Sets the id attribute. | UIAwesome\ |
isList() | Identifies this control as a list so field wrappers render a group label instead of a for label. | AbstractChoiceList |
itemAttributes() | Sets attributes applied to every item input. | AbstractChoiceList |
itemContainerAttributes() | Sets attributes applied to the container enclosing every item input and label. | AbstractChoiceList |
itemContainerClass() | Adds CSS classes to the container enclosing every item input and label. | AbstractChoiceList |
itemContainerTag() | Sets the tag enclosing every item input and label. | AbstractChoiceList |
itemId() | Sets the itemid attribute. | UIAwesome\ |
itemLabelAttributes() | Sets default attributes applied to every item label. | AbstractChoiceList |
itemLabelClass() | Adds CSS classes to every item label. | AbstractChoiceList |
itemProp() | Sets the itemprop attribute. | UIAwesome\ |
itemRef() | Sets the itemref attribute. | UIAwesome\ |
items() | Replaces the items rendered by the list. | AbstractChoiceList |
itemScope() | Sets the itemscope attribute. | UIAwesome\ |
itemType() | Sets the itemtype attribute. | UIAwesome\ |
lang() | Sets the lang attribute. | UIAwesome\ |
name() | Sets the name attribute. | UIAwesome\ |
removeAriaAttribute() | Removes an aria-* attribute. | UIAwesome\ |
removeAttribute() | Removes a specific HTML attribute from the element. | UIAwesome\ |
removeDataAttribute() | Removes a data-* attribute. | UIAwesome\ |
removeEvent() | Removes an on* event attribute. | UIAwesome\ |
render() final | Renders the tag with lifecycle hooks. | UIAwesome\ |
replaceAttributes() | Replaces all HTML attributes for the element. | UIAwesome\ |
role() | Sets the role attribute. | UIAwesome\ |
spellcheck() | Sets the spellcheck attribute. | UIAwesome\ |
style() | Sets the style attribute. | UIAwesome\ |
tabIndex() | Sets the tabindex attribute. | UIAwesome\ |
tag() static | Creates and configures a new tag instance. | UIAwesome\ |
title() | Sets the title attribute. | UIAwesome\ |
translate() | Sets the translate attribute. | UIAwesome\ |
uncheckedValue() | Sets the value submitted when no list item is selected. | AbstractChoiceList |
afterRun() protected | Post-processes rendered output. | UIAwesome\ |
beforeRun() protected | Validates state before rendering. | UIAwesome\ |
createInput() protected abstract | Creates the atomic input used for each item. | AbstractChoiceList |
getTag() protected | Returns the tag enumeration for the list container. | AbstractChoiceList |
isBeginExecuted() protected | Indicates whether this instance has an open or closing operation in the current context. | UIAwesome\ |
loadDefault() protected | Returns class-level default definitions. | UIAwesome\ |
run() protected | Renders the list container with its content, the unchecked input, and every item. | AbstractChoiceList |
runBegin() protected | Returns the opening tag for begin/end rendering. | AbstractChoiceList |
usesArrayName() protected abstract | Returns whether item names use array notation. | AbstractChoiceList |
Method details
Section titled “Method details”checked()
Section titled “checked() ”public function checked(mixed[]|bool|float|int|string|Stringable|UnitEnum|null $value): staticSets the values determining which items are checked.
Parameters
| Parameter | Type | Description |
|---|---|---|
$value | mixed[]|Stringable|UnitEnum| | Checked values. - array: Every item whose value is in the array is checked. - false: No item is checked. - true: Every item is checked. - float|: The item whose value matches is checked. - null: No item is checked. |
Returns
static: New instance with the updated checked values.
enclosedByLabel()
Section titled “enclosedByLabel() ”public function enclosedByLabel(bool $value = true): staticConfigures whether every item input and its text are enclosed by the item label.
Parameters
| Parameter | Type | Description |
|---|---|---|
$value | bool | Enclosure state. Use true to wrap the input inside its <label>, false to render the input and the label as siblings. |
Returns
static: New instance with the updated label enclosure state.
isList()
Section titled “isList() ”public function isList(): trueIdentifies this control as a list so field wrappers render a group label instead of a for label.
Returns
true: Always true.
itemAttributes()
Section titled “itemAttributes() ”public function itemAttributes(mixed[] $values): staticSets attributes applied to every item input.
Merges with the attributes already configured, so consecutive calls accumulate.
Parameters
| Parameter | Type | Description |
|---|---|---|
$values | mixed[] | Input attributes indexed by attribute name. |
Returns
static: New instance with the updated item attributes.
itemContainerAttributes()
Section titled “itemContainerAttributes() ”public function itemContainerAttributes(mixed[] $values): staticSets attributes applied to the container enclosing every item input and label.
Parameters
| Parameter | Type | Description |
|---|---|---|
$values | mixed[] | Container attributes indexed by attribute name. |
Returns
static: New instance with the updated item container attributes.
itemContainerClass()
Section titled “itemContainerClass() ”public function itemContainerClass(mixed[]|string|Stringable|UnitEnum|null $value, bool $override = false): staticAdds CSS classes to the container enclosing every item input and label.
Parameters
| Parameter | Type | Description |
|---|---|---|
$value | mixed[]|Stringable|UnitEnum| | Classes to add, or null to keep the current class list. |
$override | bool | Whether to replace the current class list instead of appending. |
Returns
static: New instance with the updated item container classes.
itemContainerTag()
Section titled “itemContainerTag() ”public function itemContainerTag(UIAwesome\Html\Interop\Block|false|UIAwesome\Html\Interop\Inline|UIAwesome\Html\Interop\Lists|UIAwesome\Html\Interop\MetadataBlock|UIAwesome\Html\Interop\Root|UIAwesome\Html\Form\Values\SelectTag|UIAwesome\Html\Interop\Table $value): staticSets the tag enclosing every item input and label.
Parameters
| Parameter | Type | Description |
|---|---|---|
$value | Block|Inline|Lists|MetadataBlock|Root|UIAwesome\|Table | Item container tag, or false to render items without wrappers. |
Returns
static: New instance with the updated item container tag.
itemLabelAttributes()
Section titled “itemLabelAttributes() ”public function itemLabelAttributes(mixed[] $values): staticSets default attributes applied to every item label.
Attributes configured directly on a ChoiceItem take precedence, while CSS classes are appended.
Parameters
| Parameter | Type | Description |
|---|---|---|
$values | mixed[] | Label attributes indexed by attribute name. |
Returns
static: New instance with the updated item label attributes.
itemLabelClass()
Section titled “itemLabelClass() ”public function itemLabelClass(mixed[]|string|Stringable|UnitEnum|null $value, bool $override = false): staticAdds CSS classes to every item label.
Parameters
| Parameter | Type | Description |
|---|---|---|
$value | mixed[]|Stringable|UnitEnum| | Classes to add, or null to keep the current class list. |
$override | bool | Whether to replace the current class list instead of appending. |
Returns
static: New instance with the updated item label classes.
items()
Section titled “items() ”public function items(UIAwesome\Html\Form\ChoiceItem ...$items): staticReplaces the items rendered by the list.
Parameters
| Parameter | Type | Description |
|---|---|---|
...$items | ChoiceItem | Item instances rendered in order. |
Returns
static: New instance with the replacement items.
uncheckedValue()
Section titled “uncheckedValue() ”public function uncheckedValue(bool|float|int|string|Stringable|UnitEnum|null $value): staticSets the value submitted when no list item is selected.
Renders a hidden input carrying the list name before the items, and is skipped when the list has no name.
The hidden input always carries the plain list name, never the name[] form used by CheckboxList items,
so that a checked item overwrites the fallback under PHP’s query-string parsing: name=0&name[]=1 yields
['1'], while name[]=0&name[]=1 would keep the fallback as ['0', '1']. Consumers that do not apply that
bracket normalization, such as the FormData API, receive name and name[] as separate keys.
Parameters
| Parameter | Type | Description |
|---|---|---|
$value | bool|Stringable|UnitEnum| | Fallback value, or null to omit the hidden input. |
Returns
static: New instance with the updated unchecked value.
createInput()
Section titled “createInput() ”abstract protected function createInput(): UIAwesome\Html\Form\InputCheckbox|UIAwesome\Html\Form\InputRadioCreates the atomic input used for each item.
Returns
InputCheckbox|InputRadio: Input element instance rendered for every item.
getTag()
Section titled “getTag() ”protected function getTag(): UIAwesome\Html\Interop\BlockReturns the tag enumeration for the list container.
Returns
Block: Tag enumeration instance for <div>.
run()
Section titled “run() ”protected function run(): stringRenders the list container with its content, the unchecked input, and every item.
The name attribute is transferred to the item inputs instead of being serialized on the container.
Returns
string: Rendered HTML for the choice list.
runBegin()
Section titled “runBegin() ”protected function runBegin(): stringReturns the opening tag for begin/end rendering.
Returns
string: Opening HTML tag for the list container.
usesArrayName()
Section titled “usesArrayName() ”abstract protected function usesArrayName(): boolReturns whether item names use array notation.
Returns
bool: true when every item input is named name[], false when items share the plain list name.