[Android] Implemented Material3 support for Image

[Dhivya-SF4094]

Note

Are you waiting for the changes in this PR to be merged?
It would be very helpful if you could test the resulting artifacts from this PR and let us know in a comment if this change resolves your issue. Thank you!

Description of Change

This pull request introduces platform-specific logic for registering image handlers on Android, enabling support for Material 3 by conditionally using a new handler. It also adds a new internal ImageHandler2 class for Android, which utilizes Google's Material ShapeableImageView for improved image rendering.

Android-specific handler registration:

• The registration of the Image handler in AppHostBuilderExtensions.cs is now conditional: if Material 3 is enabled on Android, ImageHandler2 is used; otherwise, the original ImageHandler is used. On other platforms, ImageHandler continues to be used.

New Image Handler for Material 3:

• Introduced a new internal ImageHandler2 class for Android, which overrides the platform view creation to use ShapeableImageView from Google's Material library.

Issues Fixed

Fixes #33660

Screenshot

Material 2	Material 3

[Copilot]

Pull request overview

This pull request introduces Material 3 support for the Image control on Android by creating a new internal ImageHandler2 class that uses Google's Material ShapeableImageView instead of the standard AppCompatImageView. The handler is conditionally registered based on the RuntimeFeature.IsMaterial3Enabled flag.

Changes:

• Adds new ImageHandler2.Android.cs that extends ImageHandler and overrides CreatePlatformView() to use ShapeableImageView with Material theming
• Updates handler registration in AppHostBuilderExtensions.cs to conditionally register ImageHandler2 on Android when Material 3 is enabled
• Maintains backward compatibility by continuing to use ImageHandler when Material 3 is disabled or on other platforms

Reviewed changes

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

File	Description
src/Core/src/Handlers/Image/ImageHandler2.Android.cs	New internal handler that creates ShapeableImageView with Material context wrapper for Material 3 support
src/Controls/src/Core/Hosting/AppHostBuilderExtensions.cs	Updated handler registration to conditionally use ImageHandler2 on Android when Material 3 is enabled

[kannanrs]

HI.. can these style be supported with a sample code, im more interested in the botoombar as in mdc-maui

TIA

[rmarinho]

🤖 AI Summary

📊 Expand Full Review

---

🔍 Pre-Flight — Context & Validation

---

📝 Review Session — Addressed the review concern · b461339

---

Issue: #33660 - Implement Material3 support for Image
PR: #33661 - [Android] Implemented Material3 support for Image
Author: Dhivya-SF4094 (Syncfusion partner)
Platforms Affected: Android only
Labels: platform/android, area-controls-image, material3, , partner/syncfusioncommunity
Milestone: .NET 10 Servicing
Files Changed: 3 implementation files, 0 test files

Issue Summary

When UseMaterial3 MSBuild property is enabled, the Image control should adopt Material 3 visual design. The issue is that Image currently uses Material 2-style visuals (standard AppCompatImageView) instead of Material 3-specific styling using ShapeableImageView with Material context theming.

PR's Approach

1. New ImageHandler2.Android. Internal class extending ImageHandlerthat overridesCreatePlatformView()to return aShapeableImageViewwrapped inMauiMaterialContextThemeWrapper.Create(Context), with SetAdjustViewBounds(true).cs
2. Conditional handler registration in AppHostBuilderExtensions. On Android, registers ImageHandler2whenRuntimeFeature.IsMaterial3Enabledis true, otherwise registersImageHandler. Non-Android platforms always use ImageHandler.cs
3. ImageViewExtensions.cs Updated UpdateAspect() to correctly allow SetAdjustViewBounds() for ShapeableImageView when used as Image (not ImageButton). Old code skipped bounds adjustment for ALL ShapeableImageView instances.fix

Reviewer Feedback (copilot-pull-request-reviewer)

Issue	File:Line	Status
No test coverage for ImageHandler2	`ImageHandler2.Android.cs: OPEN	19`
Handler registration not in alphabetical order	`AppHostBuilderExtensions.cs: OPEN	109`
skipped bounds adjustment for ShapeableImageView		RESOLVED
TODO comment lacks tracking issue reference	`ImageHandler2.Android.cs: OPEN	5`

Prior Agent Review Found

A prior complete agent review was found (2026-02-17, commit b461339). PR has not been updated since. Findings imported.

Fix Candidates

#	Source	Approach	Test Result	Files Changed	Notes
PR	PR #33661	New ImageHandler2 using ShapeableImageView for Material3, conditional PENDING (Gate)	3 files	Original PR	registration

---

🚦 Gate — Test Verification

---

📝 Review Session — Addressed the review concern · b461339

---

** FAILED - No tests existResult:**
Platform: android (selected)
Mode: Full Verification - BLOCKED (no tests to run)

Gate Failure Reason

No issue-specific tests were found for Issue #33660 or PR #33661. The PR contains 0 test all 3 changed files are implementation files:files

• src/Core/src/Handlers/Image/ImageHandler2.Android.cs (new)
• src/Controls/src/Core/Hosting/AppHostBuilderExtensions.cs (modified)
• src/Core/src/Platform/Android/ImageViewExtensions.cs (modified)

Tests Not Found

• src/Controls/tests/TestCases.HostApp/Issues/ does NOT existIssue33660*
• src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/ does NOT existIssue33660*
• No device tests in src/Core/tests/DeviceTests for ImageHandler2 or Material3 Image behavior

Action Required

Tests must be added before this PR can be merged. Suggested tests:

1. Device test: Verify that when Material 3 is enabled on Android, ImageHandler2 is used and the platform view is a ShapeableImageView
2. Device test: Verify UpdateAspect() correctly sets AdjustViewBounds for ImageHandler2

The write-tests-agent can help create these tests.

---

🔧 Fix — Analysis & Comparison

---

📝 Review Session — Addressed the review concern · b461339

---

Fix Candidates

#	Source	Approach	Test Result	Files Changed	Notes
PR	PR #33661	New ImageHandler2 using ShapeableImageView for Material3, conditional PENDING (Gate failed - no tests)	3 files	Original PR	registration

Exhausted: N/A (Gate failed - Phase 3 skipped)
Selected Fix: N/A - Gate did not pass; no fix candidates evaluated.

---

📋 Report — Final Recommendation

---

📝 Review Session — Addressed the review concern · b461339

---

Final Recommendation: REQUEST CHANGES##

Summary

PR #33661 introduces Material 3 support for the Image control on Android by adding a new ImageHandler2 class that uses ShapeableImageView with Material context theming. The implementation approach is reasonable and follows existing patterns in the codebase (e.g., how Button and Switch conditionally use Material 3 handlers). However, the PR is missing tests entirely, which prevents Gate from passing.

Root Cause (Issue #33660)

When UseMaterial3 is enabled on Android, the Image control continued to use AppCompatImageView (via the standard ImageHandler) instead of a Material 3-compatible view. ShapeableImageView from Google's Material library supports Material 3 theming via MauiMaterialContextThemeWrapper, enabling proper container shape, colors, elevation, and shadow behavior consistent with other Material 3 controls.

Additionally, ImageViewExtensions.UpdateAspect() had a bug where it unconditionally skipped SetAdjustViewBounds() for ALL ShapeableImageView instances (originally only intended to skip for ImageButton). Since ImageHandler2 also uses ShapeableImageView, this was correctly fixed to check both: imageView is ShapeableImageView && image is IImageButton.

Gate Result

FAILED - No tests exist for this issue. The PR contains 0 test files. Gate could not run.

Phase 3: Fix

Gate did not pass.Skipped

Code Review Findings

1. No tests - No device tests verifying that ImageHandler2 creates a ShapeableImageView on Android when Material 3 is enabled, and no tests verifying UpdateAspect() behavior on ImageHandler2.

2. Alphabetical order disrupted (AppHostBuilderExtensions.cs:98- Image handler was originally registered between GraphicsViewandLayout(alphabetical). After this PR, the#if ANDROIDblock is placed afterHybridWebView. Recommendation: Move to its original alphabetical position.109)

3. Missing newline at end of file (ImageHandler2.Android. Minor consistency issue.cs)

4. TODO without issue tracking (ImageHandler2.Android.cs: // TODO: make it public in .net 11 lacks a GitHub issue reference.5)

Looks Good:

5. ImageViewExtensions.UpdateAspect() fix is Changes from if (imageView is not ShapeableImageView) to shouldSkipBoundsAdjustment = imageView is ShapeableImageView && image is IImageButton. Correctly handles the new case where ShapeableImageView is used by both ImageButton AND ImageHandler2.correct

6. Pattern follows codebase Conditional handler registration via RuntimeFeature.IsMaterial3Enabled is consistent with how other Material 3 handlers are registered.conventions

7. MauiMaterialContextThemeWrapper.Create(Context) usage is Standard approach for Material 3 controls.correct

Recommended Actions for Author

1. Add tests ( Use write-tests-agent:blocking)
   • Device test: Verify ImageHandler2 creates ShapeableImageView when Material 3 is enabled
   • Device test: Verify UpdateAspect() sets AdjustViewBounds correctly on ShapeableImageView (Image, not ImageButton)
2. Fix alphabetical Move the #if ANDROID Image handler block between GraphicsView and Layoutordering
3. Fix missing newline at EOF in ImageHandler2.Android.cs
4. Reference tracking issue in TODO comment

---

📋 Expand PR Finalization Review

---

Title: ✅ Good

Current: [Android] Implemented Material3 support for Image

Description: ✅ Good

Description needs updates. See details below.

✨ Suggested PR Description

[!NOTE]
Are you waiting for the changes in this PR to be merged?
It would be very helpful if you could test the resulting artifacts from this PR and let us know in a comment if this change resolves your issue. Thank you!

Description of Change

This pull request introduces Material 3 support for the Android Image control by adding a new ImageHandler2 handler that uses ShapeableImageView as the platform view. It also fixes aspect-ratio adjustment logic in ImageViewExtensions to account for the new usage of ShapeableImageView by the Image control.

**1. AppHostBuilderExtensions. Conditional handler registration (Android only)**cs

On Android, the Image handler is now registered conditionally based on whether Material 3 is enabled (RuntimeFeature.IsMaterial3Enabled):

• If Material 3 is enabled: registers ImageHandler2
• Otherwise: registers the original ImageHandler

On all other platforms, the original ImageHandler is registered unconditionally (unchanged behavior).

**2. ImageHandler2.Android. New Material 3 image handler**cs

Introduced a new internal class ImageHandler2 (in src/Core/src/Handlers/Image/) that extends ImageHandler and overrides CreatePlatformView() to:

• Return a ShapeableImageView (from Google's Material library) instead of the default ImageView
• Wrap the context with MauiMaterialContextThemeWrapper to apply the Material 3 theme
• Call SetAdjustViewBounds(true) to enable proper intrinsic aspect ratio handling during measurement

The class is currently internal with a TODO to consider making it public in a future release.

**3. ImageViewExtensions. Fix aspect adjustment logic for ShapeableImageView**cs

UpdateAspect() previously skipped SetAdjustViewBounds() for all ShapeableImageView instances, because ShapeableImageView was only used by ImageButton. Now that ImageHandler2 also uses ShapeableImageView for the Image control, this blanket exclusion would incorrectly suppress aspect adjustment for Image.

The fix changes the condition to:

• Before: if (imageView is not skip bounds adjustment for any ShapeableImageViewShapeableImageView)
• After: if (!(imageView is ShapeableImageView && image is skip bounds adjustment only when the view is a ShapeableImageViewbeing used as anImageButtonIImageButton))

Issues Fixed

Fixes #33660

Screenshot

Material 2	Material 3

Code Review: ✅ Passed

Code PR #33661Review

1. No test coverage for ImageHandler2 or the conditional registration

Files: src/Core/src/Handlers/Image/ImageHandler2.Android.cs, src/Controls/src/Core/Hosting/AppHostBuilderExtensions.cs

Problem: There are no device tests (or unit tests) verifying:

1. When Material 3 is enabled, the Image handler creates a ShapeableImageView as the platform view
2. When Material 3 is disabled, the Image handler creates a standard ImageView
3. UpdateAspect() correctly applies SetAdjustViewBounds for Image (not just ImageButton) when ShapeableImageView is used

This is a behavioral change that could regress silently. The existing ImageHandlerTests only cover the base ImageHandler and don't exercise the new code path.

Recommendation: Add Android device tests to Controls.DeviceTests or Core.DeviceTests:

• Verify the platform view type is ShapeableImageView when Material 3 is enabled
• Verify SetAdjustViewBounds behavior with the new handler

---

2. Handler registration disrupts alphabetical ordering

File: src/Controls/src/Core/Hosting/AppHostBuilderExtensions.cs

Problem: The Image handler registration was moved from its original position between GraphicsView and Layout (alphabetical order) to after the HybridWebView conditional block. The method registers handlers alphabetically (CheckBox, DatePicker, Editor, Entry, GraphicsView, Image, Layout, Picker, ...), and the new placement breaks this convention.

Recommendation: Move the #if ANDROID Image handler block back between GraphicsView and Layout to maintain alphabetical ordering:

handlersCollection.AddHandler<GraphicsView, GraphicsViewHandler>();
#if ANDROID
    if (RuntimeFeature.IsMaterial3Enabled)
        handlersCollection.AddHandler<Image, ImageHandler2>();
    else
        handlersCollection.AddHandler<Image, ImageHandler>();
#else
    handlersCollection.AddHandler<Image, ImageHandler>();
#endif
handlersCollection.AddHandler<Layout, LayoutHandler>();

3. TODO comment lacks a tracking issue reference

File: src/Core/src/Handlers/Image/ImageHandler2.Android.cs, line 5

Problem: // TODO: make it public in .net 11 references a specific future release but has no associated GitHub issue to track the decision. This makes it hard to find and act on.

Recommendation: Either link to an existing tracking issue or replace with a more general comment:

// TODO: Consider making this public in a future release - see #XXXXX

4. Missing newline at end of file

File: src/Core/src/Handlers/Image/ImageHandler2.Android.cs

Problem: The diff shows \ No newline at end of file at the end of the new file. This is a minor style issue that can cause noise in future diffs.

Recommendation: Add a trailing newline at the end of the file.

---

Looks Good

ImageViewExtensions.UpdateAspect() fix is correct

The change from imageView is not ShapeableImageView to imageView is ShapeableImageView && image is IImageButton is the right fix. It correctly identifies the case where bounds adjustment should be skipped (ImageButton using ShapeableImageView) while allowing the Image control's new ShapeableImageView usage to benefit from bounds adjustment. Using IImageButton as the discriminator is appropriate since it's a stable interface boundary.

MauiMaterialContextThemeWrapper.Create(Context) used correctly

ImageHandler2.CreatePlatformView() passes Context (not this) to MauiMaterialContextThemeWrapper.Create(), and that method correctly detects if the context is already a MauiMaterialContextThemeWrapper to avoid double-wrapping. This follows the same pattern used by CheckBoxHandler and other Material 3 handlers.

Conditional registration follows existing Material 3 patterns

Using RuntimeFeature.IsMaterial3Enabled for conditional handler registration is consistent with how other controls (CheckBox, etc.) implement Material 3 behavior. The #if ANDROID guard correctly limits the new handler to Android only.

---

[sheiksyedm]

/azp run maui-pr-uitests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[Dhivya-SF4094]

Added UI tests and addressed all valid concerns.

The base branch was changed.

[sheiksyedm]

/azp run maui-pr-uitests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

The base branch was changed.

[jfversluis]

@Dhivya-SF4094 with all the latest merges and changes there is a conflict here now. Can you have a look? Thanks!

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.sh | bash -s -- 33661

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.ps1) } 33661"

[Dhivya-SF4094]

@Dhivya-SF4094 with all the latest merges and changes there is a conflict here now. Can you have a look? Thanks!

@jfversluis, resolved conflict and could you please review once.