0 follower

Final Class Yiisoft\Bootstrap5\Carousel

All Classes | Methods | Constants
InheritanceYiisoft\Bootstrap5\Carousel » Yiisoft\Widget\Widget

Carousel renders a carousel bootstrap JavaScript component.

For example:

<?= Carousel::widget()
        ->id('carouselExample')
        ->items(
            CarouselItem::to(Img::tag()->alt('First slide')->src('image-1.jpg'), active: true),
            CarouselItem::to(Img::tag()->alt('Second slide')->src('image-2.jpg')),
            CarouselItem::to(Img::tag()->alt('Third slide')->src('image-3.jpg')),
        )
?>

Public Methods

Hide inherited methods

Method Description Defined By
addAttributes() Adds a sets of attributes. Yiisoft\Bootstrap5\Carousel
addClass() Adds one or more CSS classes to the existing classes. Yiisoft\Bootstrap5\Carousel
addCssStyle() Adds a CSS style. Yiisoft\Bootstrap5\Carousel
attribute() Adds a sets attribute value. Yiisoft\Bootstrap5\Carousel
attributes() Sets the HTML attributes. Yiisoft\Bootstrap5\Carousel
autoPlaying() Sets whether it should automatically cycle through slides. Yiisoft\Bootstrap5\Carousel
captionPlaceholderTagName() Sets the tag name for the content caption placeholder. Yiisoft\Bootstrap5\Carousel
captionTagName() Sets the tag name for the content caption. Yiisoft\Bootstrap5\Carousel
class() Replaces all existing CSS classes with the specified one(s). Yiisoft\Bootstrap5\Carousel
controlNextLabel() Sets the label for the next control button. Yiisoft\Bootstrap5\Carousel
controlPreviousLabel() Sets the label for the previous control button. Yiisoft\Bootstrap5\Carousel
controls() Whether to show controls or not. Yiisoft\Bootstrap5\Carousel
crossfade() Sets the crossfade slides instead of sliding. Yiisoft\Bootstrap5\Carousel
id() Sets the ID. Yiisoft\Bootstrap5\Carousel
items() Sets the items. Yiisoft\Bootstrap5\Carousel
render() Run the widget. Yiisoft\Bootstrap5\Carousel
showIndicators() Whether to show indicators or not. Yiisoft\Bootstrap5\Carousel
theme() Sets the theme. Yiisoft\Bootstrap5\Carousel
touchSwiping() Toggles the touch swipe functionality. Yiisoft\Bootstrap5\Carousel

Constants

Hide inherited constants

Constant Value Description Defined By
CLASS_IMAGE 'd-block w-100' Yiisoft\Bootstrap5\Carousel
CLASS_SLIDE 'slide' Yiisoft\Bootstrap5\Carousel
NAME 'carousel' Yiisoft\Bootstrap5\Carousel

Method Details

Hide inherited methods

addAttributes() public method

Adds a sets of attributes.

public addAttributes( array $attributes ): self
$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 $carousel->addAttributes(['data-id' => '123']); `

 

                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 addClass( \BackedEnum|string|null $class ): self
$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.

 

                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 addCssStyle( array|string $style, boolean $overwrite = true ): self
$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 $carousel->addCssStyle('color: red');

// or $carousel->addCssStyle(['color' => 'red', 'font-weight' => 'bold']); `

 

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

Adds a sets attribute value.

public attribute( string $name, mixed $value ): self
$name string

The attribute name.
$value mixed

The attribute value.
return self

A new instance with the specified attribute added.

Example usage: `php $carousel->attribute('data-id', '123'); `

 

                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 attributes( array $attributes ): self
$attributes array

Attribute values indexed by attribute names.
return self

A new instance with the specified attributes.

 

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

Sets whether it should automatically cycle through slides.

Bootstrap supports three modes of autoplaying for carousels:

  • `carousel': Starts cycling when the page loads (recommended).
  • true: Like carousel, but waits until the first manual interaction before cycling.
  • false or empty string: Disables autoplaying completely.

When autoplaying is enabled, cycling can be paused by hovering over the carousel, focusing on it, or clicking on carousel controls/indicators.

See also https://getbootstrap.com/docs/5.3/components/carousel/#autoplaying-carousels Example usage: `php // Start cycling immediately $carousel->autoPlaying('carousel') // Start cycling after first manual interaction $carousel->autoPlaying(true) // Disable auto cycling $carousel->autoPlaying(false) `.

public autoPlaying( boolean|string $mode = 'carousel' ): self
$mode boolean|string
return self

A new instance with the specified autoplaying value.

 

                public function autoPlaying(bool|string $mode = 'carousel'): self
{
    $dataBsRide = match ($mode) {
        '', 'false', false => null,
        'true', true => 'true',
        default => 'carousel',
    };
    return $this->addAttributes(['data-bs-ride' => $dataBsRide]);
}
captionPlaceholderTagName() public method

Sets the tag name for the content caption placeholder.

public captionPlaceholderTagName( string $tag ): self
$tag string

The tag name for the content caption placeholder.
return self

A new instance with the specified tag name for the content caption placeholder.

Example usage: `php $carousel->captionPlaceholderTagName('p'); `
throws InvalidArgumentException

if the tag name is an empty string.

 

                public function captionPlaceholderTagName(string $tag): self
{
    $new = clone $this;
    $new->captionPlaceholderTagName = $tag;
    return $new;
}
captionTagName() public method

Sets the tag name for the content caption.

public captionTagName( string $tag ): self
$tag string

The tag name for the content caption.
return self

A new instance with the specified tag name for the content caption.

Example usage: `php $carousel->captionTagName('h5'); `
throws InvalidArgumentException

if the tag name is an empty string.

 

                public function captionTagName(string $tag): self
{
    $new = clone $this;
    $new->captionTagName = $tag;
    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 class( \BackedEnum|string|null $class ): self
$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 $carousel->class('custom-class', null, 'another-class', BackGroundColor::PRIMARY); `

 

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

Sets the label for the next control button.

public controlNextLabel( string $label ): self
$label string

The label for the next control button.
return self

A new instance with the specified label for the next control button.

Example usage: `php $carousel->controlNextLabel('Next'); `

 

                public function controlNextLabel(string $label): self
{
    $new = clone $this;
    $new->controlNextLabel = $label;
    return $new;
}
controlPreviousLabel() public method

Sets the label for the previous control button.

public controlPreviousLabel( string $label ): self
$label string

The label for the previous control button.
return self

A new instance with the specified label for the previous control button.

Example usage: `php $carousel->controlPreviousLabel('Previous'); `

 

                public function controlPreviousLabel(string $label): self
{
    $new = clone $this;
    $new->controlPreviousLabel = $label;
    return $new;
}
controls() public method

Whether to show controls or not.

public controls( boolean $enabled = true ): self
$enabled boolean

Whether to show controls or not. Default is true.
return self

A new instance with the specified value.

Example usage: `php $carousel->controls(false); `

 

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

Sets the crossfade slides instead of sliding.

public crossfade( boolean $enabled = true ): self
$enabled boolean

Whether to crossfade slides or not. Default is true.
return self

A new instance with the specified crossfade value.

Example usage: `php $carousel->crossfade(false); `

 

                public function crossfade(bool $enabled = true): self
{
    return $this->addClass($enabled ? 'carousel-fade' : null);
}
id() public method

Sets the ID.

public id( boolean|string $id ): self
$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 $carousel->id('my-id'); `
throws InvalidArgumentException

if the ID is an empty string or false.

 

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

Sets the items.

public items( Yiisoft\Bootstrap5\CarouselItem $items ): self
$items Yiisoft\Bootstrap5\CarouselItem

The items.
return self

A new instance with the specified items.

Example usage: `php $carousel->items(

CarouselItem::to(Img::tag()->alt('First slide')->src('image-1.jpg'), active: true),
CarouselItem::to(Img::tag()->alt('Second slide')->src('image-2.jpg')),
CarouselItem::to(Img::tag()->alt('Third slide')->src('image-3.jpg')),

);

 

                public function items(CarouselItem ...$items): self
{
    $new = clone $this;
    $new->items = $items;
    return $new;
}
render() public method

Run the widget.

public render( ): string
return string

The HTML representation of the element.
throws InvalidArgumentException

if the "id" property is an empty string or false.

 

                public function render(): string
{
    $attributes = $this->attributes;
    $classes = $attributes['class'] ?? null;
    unset($attributes['class']);
    if ($this->items === []) {
        return '';
    }
    $id = $this->getId();
    Html::addCssClass($attributes, [self::NAME, self::CLASS_SLIDE, $classes, ...$this->cssClasses]);
    return Div::tag()
        ->attributes($attributes)
        ->addContent(
            "\n",
            $this->renderItems($id),
            "\n",
            $this->controls ? $this->renderControlPrevious($id) . "\n" : '',
            $this->controls ? $this->renderControlNext($id) . "\n" : '',
        )
        ->encode(false)
        ->id($id)
        ->render();
}
showIndicators() public method

Whether to show indicators or not.

public showIndicators( boolean $enabled = true ): self
$enabled boolean

Whether to show indicators or not. Default is true.
return self

A new instance with the specified value.

Example usage: `php $carousel->showIndicators(false); `

 

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

Sets the theme.

public theme( string $theme ): self
$theme string

The theme.
return self

A new instance with the specified theme.

Example usage: `php $carousel->theme('dark'); `

 

                public function theme(string $theme): self
{
    return $this->addAttributes(['data-bs-theme' => $theme === '' ? null : $theme]);
}
touchSwiping() public method

Toggles the touch swipe functionality.

public touchSwiping( boolean $enabled = true ): self
$enabled boolean

Whether to enable the touch swipe functionality or not. Default is true.
return self

A new instance with the touch swipe functionality disabled.

Example usage: `php $carousel->touchSwiping(false); `

 

                public function touchSwiping(bool $enabled = true): self
{
    return $this->addAttributes(['data-bs-touch' => $enabled ? null : 'false']);
}