0 follower

Final Class Yiisoft\Bootstrap5\Button

All Classes | Methods | Constants

Inheritance	Yiisoft\Bootstrap5\Button » Yiisoft\Widget\Widget

Button renders a bootstrap button.

For example,

<?= Button::widget()
        ->label('Button')
        ->largeSize()
        ->variant(ButtonVariant::PRIMARY)
?>

Public Methods

Hide inherited methods

Method	Description	Defined By
active()	Sets the active state.	Yiisoft\Bootstrap5\Button
addAttributes()	Adds a sets of attributes.	Yiisoft\Bootstrap5\Button
addClass()	Adds one or more CSS classes to the existing classes.	Yiisoft\Bootstrap5\Button
addCssStyle()	Adds a CSS style.	Yiisoft\Bootstrap5\Button
ariaExpanded()	Sets the 'aria-expanded' attribute, indicating whether the element is currently expanded or collapsed.	Yiisoft\Bootstrap5\Button
attribute()	Adds a sets attribute value.	Yiisoft\Bootstrap5\Button
attributes()	Sets the HTML attributes.	Yiisoft\Bootstrap5\Button
class()	Replaces all existing CSS classes with the specified one(s).	Yiisoft\Bootstrap5\Button
disableTextWrapping()	Add `text-nowrap` CSS class to prevent text from wrapping.	Yiisoft\Bootstrap5\Button
disabled()	Sets the disable state.	Yiisoft\Bootstrap5\Button
id()	Sets the ID.	Yiisoft\Bootstrap5\Button
label()	The label.	Yiisoft\Bootstrap5\Button
link()	Whether the button should be a link.	Yiisoft\Bootstrap5\Button
render()	Run the widget.	Yiisoft\Bootstrap5\Button
reset()	Whether the button should be a reset button.	Yiisoft\Bootstrap5\Button
resetInput()	Get an instance of a reset button input.	Yiisoft\Bootstrap5\Button
size()	Sets the size.	Yiisoft\Bootstrap5\Button
submit()	Whether the button should be a "submit" button.	Yiisoft\Bootstrap5\Button
submitInput()	Get an instance of a "submit" button input.	Yiisoft\Bootstrap5\Button
tabIndex()	The `tabindex` attribute indicates that its element can be focused, and where it participates in sequential keyboard navigation (usually with the Tab key, hence the name).	Yiisoft\Bootstrap5\Button
toggle()	Sets the toggle behavior by the `data-bs-toggle` attribute, enabling interactive functionality such as `button`, `dropdown`, `modal`, and `tooltip`.	Yiisoft\Bootstrap5\Button
type()	Sets the type.	Yiisoft\Bootstrap5\Button
url()	Sets the URL of the link.	Yiisoft\Bootstrap5\Button
variant()	Set the variant.	Yiisoft\Bootstrap5\Button

Constants

Hide inherited constants

Constant	Value	Description	Defined By
NAME	'btn'		Yiisoft\Bootstrap5\Button

Method Details

Hide inherited methods

active() public method

Sets the active state.

public self active ( boolean $enabled = true )
$enabled	boolean	Whether the button should be active.
return	self	A new instance with the button active. Example usage: `php $button->active(); `

Source code

                public function active(bool $enabled = true): self
{
    return $this
        ->toggle($enabled ? TogglerType::BUTTON : null)
        ->addClass($enabled ? 'active' : null)
        ->attribute('aria-pressed', $enabled ? 'true' : null);
}

addAttributes() public method

Adds a sets of attributes.

public self addAttributes ( array $attributes )
$attributes	array	Attribute values indexed by attribute names. for example, `['id' => 'my-id']`.
return	self	A new instance with the specified attributes added. Example usage: `php $button->addAttributes(['data-id' => '123']); `

Source code

                public function addAttributes(array $attributes): self
{
    $new = clone $this;
    $new->attributes = [...$this->attributes, ...$attributes];
    return $new;
}

addClass() public method

Adds one or more CSS classes to the existing classes.

Multiple classes can be added by passing them as separate arguments. null values are filtered out automatically.

public self addClass ( \BackedEnum\|string\|null $class )
$class	\BackedEnum\|string\|null	One or more CSS class names to add. Pass `null` to skip adding a class.
return	self	A new instance with the specified CSS classes added to existing ones.

Source code

                public function addClass(BackedEnum|string|null ...$class): self
{
    $new = clone $this;
    $new->cssClasses = [...$this->cssClasses, ...$class];
    return $new;
}

addCssStyle() public method

Adds a CSS style.

public self addCssStyle ( array\|string $style, boolean $overwrite = true )
$style	array\|string	The CSS style. If the value is an array, a space will separate the values. For example, `['color' => 'red', 'font-weight' => 'bold']` will be rendered as `color: red; font-weight: bold;`. If it is a string, it will be added as is, for example, `color: red`.
$overwrite	boolean	Whether to overwrite existing styles with the same name. If `false`, the new value will be appended to the existing one.
return	self	A new instance with the specified CSS style value added. Example usage: `php $button->addCssStyle('color: red'); // or $button->addCssStyle(['color' => 'red', 'font-weight' => 'bold']); `

Source code

                public function addCssStyle(array|string $style, bool $overwrite = true): self
{
    $new = clone $this;
    Html::addCssStyle($new->attributes, $style, $overwrite);
    return $new;
}

ariaExpanded() public method

Sets the 'aria-expanded' attribute, indicating whether the element is currently expanded or collapsed.

public self ariaExpanded ( boolean $enabled = true )
$enabled	boolean	The value to set for the 'aria-expanded' attribute.
return	self	A new instance with the specified 'aria-expanded' value.

Source code

                public function ariaExpanded(bool $enabled = true): self
{
    return $this->attribute('aria-expanded', $enabled ? 'true' : 'false');
}

attribute() public method

Adds a sets attribute value.

public self attribute ( string $name, mixed $value )
$name	string	The attribute name.
$value	mixed	The attribute value.
return	self	A new instance with the specified attribute added. Example usage: `php $button->attribute('data-id', '123'); `

Source code

                public function attribute(string $name, mixed $value): self
{
    $new = clone $this;
    $new->attributes[$name] = $value;
    return $new;
}

attributes() public method

Sets the HTML attributes.

public self attributes ( array $attributes )
$attributes	array	Attribute values indexed by attribute names.
return	self	A new instance with the specified attributes.

Source code

                public function attributes(array $attributes): self
{
    $new = clone $this;
    $new->attributes = $attributes;
    return $new;
}

class() public method

Replaces all existing CSS classes with the specified one(s).

Multiple classes can be added by passing them as separate arguments. null values are filtered out automatically.

public self class ( \BackedEnum\|string\|null $class )
$class	\BackedEnum\|string\|null	One or more CSS class names to set. Pass `null` to skip setting a class.
return	self	A new instance with the specified CSS classes set. Example usage: `php $button->class('custom-class', null, 'another-class', BackGroundColor::PRIMARY); `

Source code

                public function class(BackedEnum|string|null ...$class): self
{
    $new = clone $this;
    $new->cssClasses = $class;
    return $new;
}

disableTextWrapping() public method

Add text-nowrap CSS class to prevent text from wrapping.

public self disableTextWrapping ( )
return	self	A new instance with the text wrapping disabled. Example usage: `php $button->disableTextWrapping(); `

Source code

                public function disableTextWrapping(): self
{
    return $this->addClass('text-nowrap');
}

disabled() public method

Sets the disable state.

public self disabled ( boolean $enabled = true )
$enabled	boolean	Whether the button should be disabled.
return	self	A new instance with the button disabled. Example usage: `php $button->disabled(); `

Source code

                public function disabled(bool $enabled = true): self
{
    $new = clone $this;
    $new->disabled = $enabled;
    return $new;
}

id() public method

Sets the ID.

public self id ( boolean\|string $id )
$id	boolean\|string	The ID of the component. If `true`, an ID will be generated automatically.
return	self	A new instance with the specified ID. Example usage: `php $button->id('my-id'); `

Source code

                public function id(bool|string $id): self
{
    $new = clone $this;
    $new->id = $id;
    return $new;
}

label() public method

The label.

public self label ( string\|\Stringable $label, boolean $encode = true )
$label	string\|\Stringable	The label to display on the button.
$encode	boolean	Whether the label value should be HTML-encoded. Use this when rendering user-generated content to prevent XSS attacks.
return	self	A new instance with the specified label value. Example usage: `php $button->label('Button'); `

Source code

                public function label(string|Stringable $label, bool $encode = true): self
{
    if ($encode) {
        $label = Html::encode($label);
    }
    $new = clone $this;
    $new->label = $label;
    return $new;
}

link() public static method

Whether the button should be a link.

public static self link ( string\|\Stringable $label = '', string\|null $url = null, array $constructorArguments = [], array $config = [], string\|null $theme = null )
$label	string\|\Stringable	The content.
$url	string\|null	The URL of the link.
$constructorArguments	array	The constructor arguments.
$config	array	The configuration.
$theme	string\|null	The theme.
return	self	A new instance with the button as a link. Example usage: `php Button::link('Button', '/path/to/page'); `
throws	\Yiisoft\Definitions\Exception\CircularReferenceException
throws	\Yiisoft\Definitions\Exception\InvalidConfigException
throws	\Yiisoft\Factory\NotFoundException
throws	\Yiisoft\Definitions\Exception\NotInstantiableException

Source code

                public static function link(
    string|Stringable $label = '',
    ?string $url = null,
    array $constructorArguments = [],
    array $config = [],
    ?string $theme = null,
): self {
    return self::widget($constructorArguments, $config, $theme)->label($label)->type(ButtonType::LINK)->variant(ButtonVariant::LINK)->url($url);
}

render() public method

Run the widget.

public string render ( )
return	string	The HTML representation of the element.

Source code

                public function render(): string
{
    $attributes = $this->attributes;
    $classes = $attributes['class'] ?? null;
    $tag = $this->tag ?? (new ButtonTag())->button('');
    unset($attributes['class'], $attributes['id']);
    Html::addCssClass($attributes, [self::NAME, $this->buttonVariant?->value, $classes]);
    $attributes = $this->setAttributes($attributes);
    $tag = $tag->addAttributes($attributes)->addClass(...$this->cssClasses)->id($this->getId());
    if ($tag instanceof Input) {
        if ($this->label !== '') {
            $tag = $tag->value($this->label);
        }
        return $tag->render();
    }
    return $tag->addContent($this->label)->addClass()->encode(false)->render();
}

reset() public static method

Whether the button should be a reset button.

public static self reset ( string\|\Stringable $value = 'Reset', array $constructorArguments = [], array $config = [], string\|null $theme = null )
$value	string\|\Stringable	The content. For default, it is 'Reset'.
$constructorArguments	array	The constructor arguments.
$config	array	The configuration.
$theme	string\|null	The theme.
return	self	A new instance with the button as a reset button. Example usage: `php Button::reset('Reset'); `
throws	\Yiisoft\Definitions\Exception\CircularReferenceException
throws	\Yiisoft\Definitions\Exception\InvalidConfigException
throws	\Yiisoft\Factory\NotFoundException
throws	\Yiisoft\Definitions\Exception\NotInstantiableException

Source code

                public static function reset(
    string|Stringable $value = 'Reset',
    array $constructorArguments = [],
    array $config = [],
    ?string $theme = null,
): self {
    return self::widget($constructorArguments, $config, $theme)->label($value)->type(ButtonType::RESET);
}

resetInput() public static method

Get an instance of a reset button input.

public static self resetInput ( string\|\Stringable $value = 'Reset', array $constructorArguments = [], array $config = [], string\|null $theme = null )
$value	string\|\Stringable	The content. By default, it's "Reset".
$constructorArguments	array	The constructor arguments.
$config	array	The configuration.
$theme	string\|null	The theme.
return	self	A new instance with the input of "reset" type. Example usage: `php Button::resetInput('Reset'); `
throws	\Yiisoft\Definitions\Exception\CircularReferenceException
throws	\Yiisoft\Definitions\Exception\InvalidConfigException
throws	\Yiisoft\Factory\NotFoundException
throws	\Yiisoft\Definitions\Exception\NotInstantiableException

Source code

                public static function resetInput(
    string|Stringable $value = 'Reset',
    array $constructorArguments = [],
    array $config = [],
    ?string $theme = null,
): self {
    return self::widget($constructorArguments, $config, $theme)->label($value)->type(ButtonType::RESET_INPUT);
}

size() public method

Sets the size.

public self size ( \Yiisoft\Bootstrap5\ButtonSize\|null $size )
$size	\Yiisoft\Bootstrap5\ButtonSize\|null	The size. If `null`, the size will not be set.
return	self	A new instance with the specified size. Example usage: `php $button->size(ButtonSize::LARGE); `

Source code

                public function size(?ButtonSize $size): self
{
    return $this->addClass($size?->value);
}

submit() public static method

Whether the button should be a "submit" button.

public static self submit ( string\|\Stringable $value = 'Submit', array $constructorArguments = [], array $config = [], string\|null $theme = null )
$value	string\|\Stringable	The content. For default, it is "Submit".
$constructorArguments	array	The constructor arguments.
$config	array	The configuration.
$theme	string\|null	The theme.
return	self	A new instance with the button as a "submit" button. Example usage: `php Button::submit('Submit'); `
throws	\Yiisoft\Definitions\Exception\CircularReferenceException
throws	\Yiisoft\Definitions\Exception\InvalidConfigException
throws	\Yiisoft\Factory\NotFoundException
throws	\Yiisoft\Definitions\Exception\NotInstantiableException

Source code

                public static function submit(
    string|Stringable $value = 'Submit',
    array $constructorArguments = [],
    array $config = [],
    ?string $theme = null,
): self {
    return self::widget($constructorArguments, $config, $theme)->label($value)->type(ButtonType::SUBMIT);
}

submitInput() public static method

Get an instance of a "submit" button input.

public static self submitInput ( string\|\Stringable $value = 'Submit', array $constructorArguments = [], array $config = [], string\|null $theme = null )
$value	string\|\Stringable	The content. By default, it's "Submit".
$constructorArguments	array	The constructor arguments.
$config	array	The configuration.
$theme	string\|null	The theme.
return	self	A new instance of an input with "submit" type. Example usage: `php Button::submitInput('Submit'); `
throws	\Yiisoft\Definitions\Exception\CircularReferenceException
throws	\Yiisoft\Definitions\Exception\InvalidConfigException
throws	\Yiisoft\Factory\NotFoundException
throws	\Yiisoft\Definitions\Exception\NotInstantiableException

Source code

                public static function submitInput(
    string|Stringable $value = 'Submit',
    array $constructorArguments = [],
    array $config = [],
    ?string $theme = null,
): self {
    return self::widget($constructorArguments, $config, $theme)->label($value)->type(ButtonType::SUBMIT_INPUT);
}

tabIndex() public method

The tabindex attribute indicates that its element can be focused, and where it participates in sequential keyboard navigation (usually with the Tab key, hence the name).

It accepts an integer as a value, with different results depending on the integer's value:

A negative value (usually tabindex="-1") means that the element is not reachable via sequential keyboard navigation, but could be focused with JavaScript or visually. It's mostly useful to create accessible widgets with JavaScript.
tabindex="0" means that the element should be focusable in sequential keyboard navigation, but its order is defined by the document's source order.
A positive value means the element should be focusable in sequential keyboard navigation, with its order defined by the value of the number. That is, tabindex="4" is focused before tabindex="5", but after tabindex="3".

public self tabIndex ( ?int $value )
$value	?int

Source code

                public function tabIndex(?int $value): self
{
    return $this->attribute('tabindex', $value);
}

toggle() public method

Sets the toggle behavior by the data-bs-toggle attribute, enabling interactive functionality such as button, dropdown, modal, and tooltip.

public self toggle ( \Yiisoft\Bootstrap5\Utility\TogglerType\|null $type = TogglerType::BUTTON )
$type	\Yiisoft\Bootstrap5\Utility\TogglerType\|null	The toggle type to be set. If `null`, the toggle behavior will not be set.
return	self	A new instance with the specified toggle behavior. Example usage: `php $button->toggle(TogglerType::BUTTON); `

Source code

                public function toggle(?TogglerType $type = TogglerType::BUTTON): self
{
    return $this->attribute('data-bs-toggle', $type?->value);
}

type() public method

Sets the type.

public self type ( \Yiisoft\Bootstrap5\ButtonType $type )
$type	\Yiisoft\Bootstrap5\ButtonType	The type.
return	self	A new instance with the specified type. Example usage: `php $button->type(ButtonType::LINK); `

Source code

                public function type(ButtonType $type): self
{
    $new = clone $this;
    $new->tag = match ($type) {
        ButtonType::LINK => (new A()),
        ButtonType::RESET => ButtonTag::reset(''),
        ButtonType::RESET_INPUT => Input::resetButton(),
        ButtonType::SUBMIT => ButtonTag::submit(''),
        ButtonType::SUBMIT_INPUT => Input::submitButton(),
    };
    return $new;
}

url() public method

Sets the URL of the link.

public self url ( string\|null $url )
$url	string\|null	The URL of the link.
return	self	A new instance with the specified URL. Example usage: `php $button->url('/path/to/page'); `

Source code

                public function url(?string $url): self
{
    return $this->attribute('href', $url);
}

variant() public method

Set the variant.

public self variant ( \Yiisoft\Bootstrap5\ButtonVariant\|null $variant )
$variant	\Yiisoft\Bootstrap5\ButtonVariant\|null	The variant. If `null`, the variant will not be set.
return	self	A new instance with the specified variant. Example usage: `php $button->variant(ButtonVariant::PRIMARY); `

Source code

                public function variant(?ButtonVariant $variant): self
{
    $new = clone $this;
    $new->buttonVariant = $variant;
    return $new;
}