feat: Add LazyLoadImages toggle to Carousel block with per-slide override option

[mi5t4n]

Summary

Add LazyLoadImages toggle to Carousel block with per-slide override option

Type of change

• Bug fix
• New feature
• Enhancement/refactor
• Documentation update
• Test update
• Build/CI/tooling

Related issue(s)

Closes #93

What changed

• Added "Lazy Load Images" toggle to Carousel block (enabled by default)
• Added "Disable Lazy Load Images" toggle to Slide block (disabled by default)
• Added render_block filter in Plugin.php using WP_HTML_Tag_Processor to add
  loading="lazy" attribute to images inside carousel slides

Breaking changes

Does this introduce a breaking change? If yes, describe the impact and migration path below.

• Yes — migration path:
• No

Testing

• Unit tests
• Manual testing
• Cross-browser testing (if UI changes)

Test details:

Prerequisites

• WordPress 6.2+ with Gutenberg enabled
• Carousel Kit plugin installed and activated
  Test Cases

1. Carousel Block - Lazy Load Images Toggle
2. Add a Carousel block to a post/page
3. Open Carousel Settings panel in block inspector
4. Verify "Lazy Load Images" toggle is present (after "Free Drag")
5. Toggle OFF and verify images don't get loading="lazy"
6. Toggle ON and verify images get loading="lazy"
7. Slide Block - Disable Lazy Load Images Toggle
8. Select a slide in the carousel
9. Open Slide Settings panel in block inspector
10. Verify "Disable Lazy Load Images" toggle is present
11. Toggle ON - images in that slide should not have loading="lazy"
12. Toggle OFF - images in that slide should have loading="lazy"
13. Default Behavior

• Fresh carousel: lazyLoadImages should be ON by default
• Fresh slide: disableLazyLoadImages should be OFF by default
• Images should have loading="lazy" by default

4. Edge Cases

• Carousel with lazyLoadImages: OFF - no images should be lazy loaded
• Slide with disableLazyLoadImages: ON - images in that slide bypass parent setting
• Images already having loading attribute - should not be overridden
  Verification
  View page source to confirm tags have loading="lazy" attribute when enabled.

Screenshots / recordings

1. Enable Lazyload Toggle in Carousel Block

2. Disable Lazyload in Carousel Slide Block

3. Markup modified

If applicable, add screenshots or short recordings.

Checklist

• I have self-reviewed this PR
• I have added/updated tests where needed
• I have updated docs where needed
• I have checked for breaking changes

[Copilot]

Pull request overview

Adds configurable image lazy-loading to the Carousel Kit blocks by introducing a carousel-level toggle with a per-slide opt-out, and applying the behavior on render via a WordPress block render filter.

Changes:

• Added lazyLoadImages attribute + inspector toggle to the Carousel block (default: enabled).
• Added disableLazyLoadImages attribute + inspector toggle to the Slide block (default: disabled).
• Added a render_block_carousel-kit/carousel-slide filter that uses WP_HTML_Tag_Processor to add loading="lazy" to <img> tags when enabled.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/blocks/carousel/types.ts	Extends block attribute types to include carousel/slide lazy-load flags.
src/blocks/carousel/edit.tsx	Adds the Carousel inspector toggle wiring for lazyLoadImages.
src/blocks/carousel/block.json	Persists lazyLoadImages with default true and exposes it via block context.
src/blocks/carousel/slide/edit.tsx	Adds Slide inspector toggle for disableLazyLoadImages.
src/blocks/carousel/slide/block.json	Persists disableLazyLoadImages and declares the carousel context dependency.
src/blocks/carousel/__tests__/types.test.ts	Updates TS type tests to include lazyLoadImages.
inc/Plugin.php	Implements server-side HTML mutation to add loading="lazy" based on context + slide attrs.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (1)

src/blocks/carousel/tests/types.test.ts:66

• In the “should have all required properties” test, lazyLoadImages is now a required attribute but it isn’t included in the requiredKeys list that the test iterates over. This makes the runtime key-presence assertion incomplete; please add lazyLoadImages to that list so the test actually verifies the new required attribute is present.

				lazyLoadImages: false,
			};

			// Verify all keys exist
			const requiredKeys = [

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[sanketio]

@mi5t4n Thank you for the PR for this.

I have a few questions.

---

On the need for disableLazyLoadImages — is the per-slide attribute necessary?

The case where you'd want a slide's images to not be lazy-loaded seem to be: the first slide — deterministic, could be handled automatically by slide position.

Could the feature be simplified by removing disableLazyLoadImages entirely and moving the filter to the carousel level with first-slide exclusion baked in?

Current (hooked per-slide, no position awareness):

add_filter( 'render_block_carousel-kit/carousel-slide', [ $this, 'handle_lazy_load_images' ], 10, 3 );

// Fires once per slide — 8 slides = 8 WP_HTML_Tag_Processor instances.
// No way to know if this is the first slide.

Suggestion (hooked once at the carousel level, position-aware):

add_filter( 'render_block_carousel-kit/carousel', [ $this, 'handle_lazy_load_images' ], 10, 2 );

public function handle_lazy_load_images( string $block_content, array $parsed_block ): string {
    if ( is_admin() ) {
        return $block_content;
    }

    $lazy_load = (bool) ( $parsed_block['attrs']['lazyLoadImages'] ?? true );
    if ( ! $lazy_load ) {
        return $block_content;
    }

    $processor      = new WP_HTML_Tag_Processor( $block_content );
    $slide_index    = -1;
    $in_first_slide = false;

    while ( $processor->next_tag() ) {
        $tag = $processor->get_tag();

        if ( 'DIV' === $tag && $processor->has_class( 'embla__slide' ) ) {
            $slide_index++;
            $in_first_slide = ( 0 === $slide_index );
        }

        if ( 'IMG' !== $tag || null !== $processor->get_attribute( 'loading' ) ) {
            continue;
        }

        if ( $in_first_slide ) {
            $processor->set_attribute( 'loading', 'eager' );
            $processor->set_attribute( 'fetchpriority', 'high' );
        } else {
            $processor->set_attribute( 'loading', 'lazy' );
        }
    }

    return $processor->get_updated_html();
}

This also means the disableLazyLoadImages attribute, context entry, and slide-level toggle can all be removed.

---

On WordPress core's native lazy loading — is this already handled?

Worth checking: wp_filter_content_tags() runs after all render_block filters and adds loading="lazy" to any <img> without a loading attribute. And core/image blocks already get their loading attribute set during their own render via wp_img_tag_add_loading_optimization_attrs() — which means the null === $processor->get_attribute( 'loading' ) guard would skip them anyway. Is there a specific scenario this filter covers that core doesn't already handle?

---

The PR checklist marks tests as added, but PluginTest.php doesn't seem to have coverage for handle_lazy_load_images yet. Would it be worth adding the three core paths using the existing invokeMethod helper?

Suggestions:

public function test_handle_lazy_load_images_returns_early_when_disabled(): void {
    $instance          = \Mockery::mock( \WP_Block::class );
    $instance->context = [ 'carousel-kit/carousel/lazyLoadImages' => false ];

    $block_content = '<div><img src="test.jpg" /></div>';
    $parsed_block  = [ 'attrs' => [] ];

    $plugin = $this->getPluginInstance();
    $result = $this->invokeMethod( $plugin, 'handle_lazy_load_images', [ $block_content, $parsed_block, $instance ] );

    $this->assertSame( $block_content, $result );
}

public function test_handle_lazy_load_images_respects_per_slide_disable(): void {
    $instance          = \Mockery::mock( \WP_Block::class );
    $instance->context = [ 'carousel-kit/carousel/lazyLoadImages' => true ];

    $block_content = '<div><img src="test.jpg" /></div>';
    $parsed_block  = [ 'attrs' => [ 'disableLazyLoadImages' => true ] ];

    $plugin = $this->getPluginInstance();
    $result = $this->invokeMethod( $plugin, 'handle_lazy_load_images', [ $block_content, $parsed_block, $instance ] );

    $this->assertSame( $block_content, $result );
}

public function test_handle_lazy_load_images_does_not_override_existing_loading(): void {
    $instance          = \Mockery::mock( \WP_Block::class );
    $instance->context = [ 'carousel-kit/carousel/lazyLoadImages' => true ];

    $block_content = '<div><img src="test.jpg" loading="eager" /></div>';
    $parsed_block  = [ 'attrs' => [] ];

    $plugin = $this->getPluginInstance();
    $result = $this->invokeMethod( $plugin, 'handle_lazy_load_images', [ $block_content, $parsed_block, $instance ] );

    $this->assertStringContainsString( 'loading="eager"', $result );
    $this->assertStringNotContainsString( 'loading="lazy"', $result );
}

[sanketio]

Minor PHPCS note — there's a trailing blank line before the closing } of the while block that might trigger a sniff:

Suggestion:

while ( $processor->next_tag( 'img' ) ) {
    if ( null === $processor->get_attribute( 'loading' ) ) {
        $processor->set_attribute( 'loading', 'lazy' );
    }
}

[milindmore22]

Overall needs a lint check.

----------------------------------------------------------------------------------------------------------------------------------
FOUND 3 ERRORS AND 2 WARNINGS AFFECTING 4 LINES
----------------------------------------------------------------------------------------------------------------------------------
 295 | WARNING | [x] Equals sign not aligned with surrounding assignments; expected 3 spaces but found 1 space
     |         |     (Generic.Formatting.MultipleStatementAlignment.NotSameWarning)
 298 | ERROR   | [x] Space after opening parenthesis of function call prohibited
     |         |     (PEAR.Functions.FunctionCallSignature.SpaceAfterOpenBracket)
 298 | ERROR   | [x] Expected 0 spaces before closing parenthesis; 2 found
     |         |     (PEAR.Functions.FunctionCallSignature.SpaceBeforeCloseBracket)
 303 | WARNING | [x] Stand-alone post-increment statement found. Use pre-increment instead: ++$slide_index.
     |         |     (Universal.Operators.DisallowStandalonePostIncrementDecrement.PostIncrementFound)
 307 | ERROR   | [x] Use early exit to reduce code nesting. (SlevomatCodingStandard.ControlStructures.EarlyExit.EarlyExitNotUsed)
----------------------------------------------------------------------------------------------------------------------------------
PHPCBF CAN FIX THE 5 MARKED SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------------------------------------------------------------------

[milindmore22]

space after opening parathesis

[milindmore22]

Use pre-increment instead: ++$slide_index.

[milindmore22]

use early exist