Skip to content
PHP Ecosystem
Explore

AbstractChoiceList

API reference › HTML › Form › AbstractChoiceList

abstract classUIAwesome\Html\Form\AbstractChoiceList
ExtendsUIAwesome\Html\Core\Element\BaseBlock » UIAwesome\Html\Core\Base\BaseTag
ImplementsUIAwesome\Html\Contracts\Form\CheckedStateInterface, UIAwesome\Html\Contracts\Form\ChoiceListInterface, UIAwesome\Html\Contracts\Form\FormControlInterface, UIAwesome\Html\Contracts\Attribute\AttributesInterface, UIAwesome\Html\Contracts\Element\BlockInterface, UIAwesome\Html\Contracts\Element\ClearableContentInterface, UIAwesome\Html\Contracts\RenderableInterface
Uses traitsUIAwesome\Html\Attribute\HasName, UIAwesome\Html\Attribute\Global\CanBeAutofocus, UIAwesome\Html\Attribute\Global\CanBeHidden, UIAwesome\Html\Attribute\Global\HasAccesskey, UIAwesome\Html\Attribute\Global\HasAria, UIAwesome\Html\Mixin\HasAttributes, UIAwesome\Html\Attribute\Global\HasClass, UIAwesome\Html\Mixin\HasContent, UIAwesome\Html\Attribute\Global\HasContentEditable, UIAwesome\Html\Attribute\Global\HasData, UIAwesome\Html\Attribute\Global\HasDir, UIAwesome\Html\Attribute\Global\HasDraggable, UIAwesome\Html\Attribute\Global\HasEvents, UIAwesome\Html\Attribute\Global\HasId, UIAwesome\Html\Attribute\Global\HasLang, UIAwesome\Html\Attribute\Global\HasMicroData, UIAwesome\Html\Attribute\Global\HasRole, UIAwesome\Html\Attribute\Global\HasSpellcheck, UIAwesome\Html\Attribute\Global\HasStyle, UIAwesome\Html\Attribute\Global\HasTabindex, UIAwesome\Html\Attribute\Global\HasTitle, UIAwesome\Html\Attribute\Global\HasTranslate, UIAwesome\Html\Core\Event\HasAfterRun, UIAwesome\Html\Core\Event\HasBeforeRun
Sourcesrc/Form/AbstractChoiceList.php
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.

PropertyTypeDescriptionDefined by
$attributes protectedmixed[]HTML attributes array used by the implementing class. Default: [].UIAwesome\Html\Mixin\HasAttributes
$content protectedstringContent string assigned to the element. Default: ''.UIAwesome\Html\Mixin\HasContent
MethodDescriptionDefined by
__construct() finalInitializes a new tag instance.UIAwesome\Html\Core\Base\BaseTag
__toString()Returns the rendered tag string.UIAwesome\Html\Core\Base\BaseTag
accesskey()Sets the accesskey attribute.UIAwesome\Html\Attribute\Global\HasAccesskey
addAriaAttribute()Sets an aria-* attribute.UIAwesome\Html\Attribute\Global\HasAria
addAttribute()Adds or updates a single HTML attribute for the element.UIAwesome\Html\Mixin\HasAttributes
addDataAttribute()Sets a data-* attribute.UIAwesome\Html\Attribute\Global\HasData
addEvent()Sets an on* event attribute.UIAwesome\Html\Attribute\Global\HasEvents
ariaAttributes()Sets multiple aria-* attributes.UIAwesome\Html\Attribute\Global\HasAria
attributes()Adds or updates multiple HTML attributes for the element.UIAwesome\Html\Mixin\HasAttributes
autofocus()Sets the autofocus attribute.UIAwesome\Html\Attribute\Global\CanBeAutofocus
begin() finalStarts begin/end rendering for this instance.UIAwesome\Html\Core\Element\BaseBlock
checked()Sets the values determining which items are checked.AbstractChoiceList
class()Sets the class attribute.UIAwesome\Html\Attribute\Global\HasClass
clearContent()Clears encoded and raw content without changing other component state.UIAwesome\Html\Mixin\HasContent
config()Applies application-scoped config recipes to this tag.UIAwesome\Html\Core\Base\BaseTag
content()Appends encoded content.UIAwesome\Html\Mixin\HasContent
contentEditable()Sets the contenteditable attribute.UIAwesome\Html\Attribute\Global\HasContentEditable
dataAttributes()Sets multiple data-* attributes.UIAwesome\Html\Attribute\Global\HasData
dir()Sets the dir attribute.UIAwesome\Html\Attribute\Global\HasDir
draggable()Sets the draggable attribute.UIAwesome\Html\Attribute\Global\HasDraggable
enclosedByLabel()Configures whether every item input and its text are enclosed by the item label.AbstractChoiceList
end() static finalEnds the most recent begin/end rendering block for the current class.UIAwesome\Html\Core\Element\BaseBlock
events()Sets multiple on* event attributes.UIAwesome\Html\Attribute\Global\HasEvents
getAttribute()Returns the value of a single HTML attribute.UIAwesome\Html\Mixin\HasAttributes
getAttributes()Returns the array of HTML attributes for the element.UIAwesome\Html\Mixin\HasAttributes
getContent()Returns the content assigned to the element.UIAwesome\Html\Mixin\HasContent
hidden()Sets the hidden attribute.UIAwesome\Html\Attribute\Global\CanBeHidden
html()Appends trusted raw HTML content without encoding or sanitizing it.UIAwesome\Html\Mixin\HasContent
id()Sets the id attribute.UIAwesome\Html\Attribute\Global\HasId
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\Html\Attribute\Global\HasMicroData
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\Html\Attribute\Global\HasMicroData
itemRef()Sets the itemref attribute.UIAwesome\Html\Attribute\Global\HasMicroData
items()Replaces the items rendered by the list.AbstractChoiceList
itemScope()Sets the itemscope attribute.UIAwesome\Html\Attribute\Global\HasMicroData
itemType()Sets the itemtype attribute.UIAwesome\Html\Attribute\Global\HasMicroData
lang()Sets the lang attribute.UIAwesome\Html\Attribute\Global\HasLang
name()Sets the name attribute.UIAwesome\Html\Attribute\HasName
removeAriaAttribute()Removes an aria-* attribute.UIAwesome\Html\Attribute\Global\HasAria
removeAttribute()Removes a specific HTML attribute from the element.UIAwesome\Html\Mixin\HasAttributes
removeDataAttribute()Removes a data-* attribute.UIAwesome\Html\Attribute\Global\HasData
removeEvent()Removes an on* event attribute.UIAwesome\Html\Attribute\Global\HasEvents
render() finalRenders the tag with lifecycle hooks.UIAwesome\Html\Core\Base\BaseTag
replaceAttributes()Replaces all HTML attributes for the element.UIAwesome\Html\Mixin\HasAttributes
role()Sets the role attribute.UIAwesome\Html\Attribute\Global\HasRole
spellcheck()Sets the spellcheck attribute.UIAwesome\Html\Attribute\Global\HasSpellcheck
style()Sets the style attribute.UIAwesome\Html\Attribute\Global\HasStyle
tabIndex()Sets the tabindex attribute.UIAwesome\Html\Attribute\Global\HasTabindex
tag() staticCreates and configures a new tag instance.UIAwesome\Html\Core\Base\BaseTag
title()Sets the title attribute.UIAwesome\Html\Attribute\Global\HasTitle
translate()Sets the translate attribute.UIAwesome\Html\Attribute\Global\HasTranslate
uncheckedValue()Sets the value submitted when no list item is selected.AbstractChoiceList
afterRun() protectedPost-processes rendered output.UIAwesome\Html\Core\Event\HasAfterRun
beforeRun() protectedValidates state before rendering.UIAwesome\Html\Core\Event\HasBeforeRun
createInput() protected abstractCreates the atomic input used for each item.AbstractChoiceList
getTag() protectedReturns the tag enumeration for the list container.AbstractChoiceList
isBeginExecuted() protectedIndicates whether this instance has an open or closing operation in the current context.UIAwesome\Html\Core\Element\BaseBlock
loadDefault() protectedReturns class-level default definitions.UIAwesome\Html\Core\Base\BaseTag
run() protectedRenders the list container with its content, the unchecked input, and every item.AbstractChoiceList
runBegin() protectedReturns the opening tag for begin/end rendering.AbstractChoiceList
usesArrayName() protected abstractReturns whether item names use array notation.AbstractChoiceList
public function checked(mixed[]|bool|float|int|string|Stringable|UnitEnum|null $value): static

Sets the values determining which items are checked.

Parameters

ParameterTypeDescription
$valuemixed[]|bool|float|int|string|Stringable|UnitEnum|nullChecked values. - array: Every item whose value is in the array is checked. - false: No item is checked. - true: Every item is checked. - float|int|string|Stringable|UnitEnum: The item whose value matches is checked. - null: No item is checked.

Returns

static: New instance with the updated checked values.

public function enclosedByLabel(bool $value = true): static

Configures whether every item input and its text are enclosed by the item label.

Parameters

ParameterTypeDescription
$valueboolEnclosure 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.

public function isList(): true

Identifies this control as a list so field wrappers render a group label instead of a for label.

Returns

true: Always true.

public function itemAttributes(mixed[] $values): static

Sets attributes applied to every item input.

Merges with the attributes already configured, so consecutive calls accumulate.

Parameters

ParameterTypeDescription
$valuesmixed[]Input attributes indexed by attribute name.

Returns

static: New instance with the updated item attributes.

public function itemContainerAttributes(mixed[] $values): static

Sets attributes applied to the container enclosing every item input and label.

Parameters

ParameterTypeDescription
$valuesmixed[]Container attributes indexed by attribute name.

Returns

static: New instance with the updated item container attributes.

public function itemContainerClass(mixed[]|string|Stringable|UnitEnum|null $value, bool $override = false): static

Adds CSS classes to the container enclosing every item input and label.

Parameters

ParameterTypeDescription
$valuemixed[]|string|Stringable|UnitEnum|nullClasses to add, or null to keep the current class list.
$overrideboolWhether to replace the current class list instead of appending.

Returns

static: New instance with the updated item container classes.

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): static

Sets the tag enclosing every item input and label.

Parameters

ParameterTypeDescription
$valueBlock|false|Inline|Lists|MetadataBlock|Root|UIAwesome\Html\Form\Values\SelectTag|TableItem container tag, or false to render items without wrappers.

Returns

static: New instance with the updated item container tag.

public function itemLabelAttributes(mixed[] $values): static

Sets default attributes applied to every item label.

Attributes configured directly on a ChoiceItem take precedence, while CSS classes are appended.

Parameters

ParameterTypeDescription
$valuesmixed[]Label attributes indexed by attribute name.

Returns

static: New instance with the updated item label attributes.

public function itemLabelClass(mixed[]|string|Stringable|UnitEnum|null $value, bool $override = false): static

Adds CSS classes to every item label.

Parameters

ParameterTypeDescription
$valuemixed[]|string|Stringable|UnitEnum|nullClasses to add, or null to keep the current class list.
$overrideboolWhether to replace the current class list instead of appending.

Returns

static: New instance with the updated item label classes.

public function items(UIAwesome\Html\Form\ChoiceItem ...$items): static

Replaces the items rendered by the list.

Parameters

ParameterTypeDescription
...$itemsChoiceItemItem instances rendered in order.

Returns

static: New instance with the replacement items.

public function uncheckedValue(bool|float|int|string|Stringable|UnitEnum|null $value): static

Sets 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

ParameterTypeDescription
$valuebool|float|int|string|Stringable|UnitEnum|nullFallback value, or null to omit the hidden input.

Returns

static: New instance with the updated unchecked value.

abstract protected function createInput(): UIAwesome\Html\Form\InputCheckbox|UIAwesome\Html\Form\InputRadio

Creates the atomic input used for each item.

Returns

InputCheckbox|InputRadio: Input element instance rendered for every item.

protected function getTag(): UIAwesome\Html\Interop\Block

Returns the tag enumeration for the list container.

Returns

Block: Tag enumeration instance for <div>.

protected function run(): string

Renders 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.

protected function runBegin(): string

Returns the opening tag for begin/end rendering.

Returns

string: Opening HTML tag for the list container.

abstract protected function usesArrayName(): bool

Returns whether item names use array notation.

Returns

bool: true when every item input is named name[], false when items share the plain list name.