Image Swiper

TODO: Build Image Swiper

The Image Swiper is a responsive, swipeable carousel for full-bleed images with an optional overlaid title.
It consists of an image-swiper container (outer Swiper instance) and one or more image-swiper-item blocks (slides).
Spacing is controlled via SpacerSettings, and slider behavior is configured via SwiperSettings.

Default Attributes

Image Swiper (Container)

Attribute	Type	Default	Description
uuid	string	""	Unique identifier generated per swiper instance (used to scope controls).
spacer	string	”medium”	Controls vertical spacing classes for the section wrapper.
pagination	string	”false”	Enables pagination bullets when set to `"true"`.
navigation	string	”false”	Enables next/prev arrows when set to `"true"`.
(swiper attrs)	mixed	—	Additional options provided by `SwiperSettings` UI.

The container also inherits attributes from your shared defaultSwiperAttributes and defaultSpacerAttributes.

Image Swiper Item

Attribute	Type	Default	Description
(image attributes)	mixed	—	Provided by `getDefaultImageAttributes` (e.g., `mediaUrl`, `alt`, …).
title	string	""	Optional overlay title centered on the image.

Component Breakdown

Block Registration (Container)

registerBlockType('basetheme/image-swiper', {
    title: 'Image Swiper',
    icon: layout,
    category: 'layout',
    description: 'A Description',
    keywords: '[]',
    supports: {},
    attributes: {
        uuid: { type: 'string', default: '' },
        ...defaultSwiperAttributes,
        ...defaultSpacerAttributes,
    },
    parent: ['basetheme/container'],
    edit: EditComponent,
    save: SaveComponent,
});

What This Does:

Registers basetheme/image-swiper as the container block.
Merges defaultSwiperAttributes and defaultSpacerAttributes into the block’s attributes.
Uses EditComponent to expose Spacer and Swiper controls, and SaveComponent to output the inner content.

Attributes

uuid (string): Automatically generated per instance to isolate Swiper controls.
spacer (string): From defaultSpacerAttributes, controls vertical spacing classes.
swiper options: From defaultSwiperAttributes, surfaced in the SwiperSettings panel.

Edit Component (Container)

function EditComponent(props) {
    const { attributes, setAttributes } = props;

    useEffect(() => {
        if (!attributes.uuid) {
            setAttributes({ uuid: uuidv4() });
        }
    }, [attributes.uuid, setAttributes]);

    const allowedBlocks = ['basetheme/image-swiper-item'];
    const template = [['basetheme/image-swiper-item']];

    const blockProps = useBlockProps({ className: 'image-swiper__wrapper' });
    const innerBlocksProps = useInnerBlocksProps(
        { className: 'image-swiper__inner' },
        { allowedBlocks, template, templateLock: false }
    );

    return (
        <>
            <InspectorControls>
                <SpacerSettings
                    title="Container Settings"
                    attributes={attributes}
                    setAttributes={setAttributes}
                />
                <SwiperSettings
                    title="Image Swiper Settings"
                    attributes={attributes}
                    setAttributes={setAttributes}
                />
            </InspectorControls>

            <div
                className={`border border-light p-2 bg-gray-100 ${spacerClass(attributes.spacer)}`}
            >
                <div {...blockProps}>
                    <div {...innerBlocksProps} />
                </div>
            </div>
        </>
    );
}

Features:

UUID Generation: Ensures each swiper gets a unique ID for scoping navigation/pagination elements.
Inspector Controls: Provides Spacer and Swiper configuration panels.
Inner Blocks: Restricts to image-swiper-item and seeds a default slide via template.

Save Component (Container)

function SaveComponent() {
    return <InnerBlocks.Content />;
}

Features:

Outputs the nested slides; Swiper scaffold & init are handled in PHP.

PHP Rendering

Container (`image-swiper.php`)

<?php

use basetheme\Utilities\Swiper_Utils;
use basetheme\Utilities\Spacer_Utils;

Swiper_Utils::init_swiper($attributes);

if (!isset($attributes["spacer"])) {
    $attributes["spacer"] = "medium";
}

$spacer = Spacer_Utils::render_spacer($attributes['spacer']);
?>

<section class="bs-image-swiper container <?php echo $spacer; ?>">
    <div class="image-swiper swiper swiper-id-<?php echo $attributes["uuid"]; ?>"
        data-swiper <?php echo Swiper_Utils::render_swiper_settings($attributes); ?>>

        <div class="swiper-wrapper">
            <?php echo $content; ?>
        </div>

        <?php if ($attributes["pagination"] == 'true') : ?>
            <div class="swiper-pagination swiper-pagination-id-<?php echo $attributes["uuid"]; ?>"></div>
        <?php endif; ?>
        <?php if ($attributes["navigation"] == 'true') : ?>
            <div class="swiper-button-prev swiper-button__prev-id-<?php echo $attributes["uuid"]; ?>"></div>
            <div class="swiper-button-next swiper-button__next-id-<?php echo $attributes["uuid"]; ?>"></div>
        <?php endif; ?>
    </div>
</section>

Notes:

Swiper_Utils::init_swiper($attributes) should enqueue/initialize Swiper assets once.
Swiper_Utils::render_swiper_settings($attributes) outputs data- attributes consumed by your frontend Swiper init.
uuid ensures multiple instances can coexist without conflicting selectors.

Image Swiper Item

Block Registration

registerBlockType('basetheme/image-swiper-item', {
    title: 'Image Swiper Item',
    icon: layout,
    category: 'layout',
    parent: ['basetheme/image-swiper'],
    description: 'A Description',
    keywords: '[]',
    supports: {},
    attributes: {
        ...getDefaultImageAttributes,
        title: { type: 'string', default: '' },
    },
    edit: EditComponent,
    save: () => null,
});

What This Does:

Registers basetheme/image-swiper-item as a child-only block of the container.
Pulls in image attributes via getDefaultImageAttributes and adds an optional title overlay.

Attributes

image (mixed): From getDefaultImageAttributes (e.g., mediaUrl, alt, size, …).
title (string): Optional title shown centered over the image.

Edit Component (Item)

function EditComponent(props) {
    const { attributes, setAttributes } = props;

    return (
        <>
            <InspectorControls>
                <ImageSettings
                    attributes={attributes}
                    setAttributes={setAttributes}
                    imageSizeOptions={[
                        { value: 'pageBanner', label: 'Banner' },
                        { value: 'full', label: 'Full' },
                        { value: 'medium', label: 'Medium' },
                    ]}
                />
            </InspectorControls>

            <div className="position-relative">
                <div className="ratio ratio-16x9">
                    <Image mediaUrl={attributes.mediaUrl} variant="cover" />
                </div>
                <div className="position-absolute w-100 top-50 start-50 translate-middle z-1">
                    <RichText
                        value={attributes.title}
                        onChange={(title) => setAttributes({ title })}
                        placeholder="Title"
                        className="fs-72 fw-bold text-white border border-light p-2 text-center"
                    />
                </div>
            </div>
        </>
    );
}

Features:

Configures the image via ImageSettings; shows a 16:9 preview using your <Image /> utility with variant="cover".
Provides a centered overlay title editable via RichText.

PHP Rendering (Item)

<?php

use basetheme\Utilities\Image_Utils;

Image_Utils::init_image($attributes);

if (!isset($attributes["title"])) {
    $attributes["title"] = "";
}
?>

<div class="swiper-slide image-swiper-item">
  <div class="position-relative">
    <div class="ratio ratio-16x9">
      <?php Image_Utils::render_image($attributes, "img-fluid object-fit-cover"); ?>
    </div>
  </div>
  <?php if ($attributes["title"]): ?>
    <div class="position-absolute top-50 start-50 translate-middle">
      <div class="fs-72 fw-bold text-white"><?php echo $attributes["title"]; ?></div>
    </div>
  <?php endif; ?>
</div>

Notes:

The overlay is conditionally rendered only when title is provided.
Consider adding a gradient or backdrop for legibility on bright images.

Summary

The Image Swiper:

Provides a responsive Swiper carousel with optional pagination and navigation controls.
Uses a container + item pattern and a unique uuid per instance for scoped controls.
Leverages shared Spacer, Swiper, and Image utilities for consistent UI and output.
Supports an optional centered title overlay for each slide.

Image Swiper

Default Attributes

Image Swiper (Container)

Image Swiper Item

Component Breakdown

Block Registration (Container)

Edit Component (Container)

Save Component (Container)

PHP Rendering

Container (image-swiper.php)

Image Swiper Item

Block Registration

Edit Component (Item)

PHP Rendering (Item)

Summary

Container (`image-swiper.php`)