ToggleButtonExtender

March 15, 2026 · View on GitHub

The ToggleButtonExtender replaces a target checkbox with a clickable image that toggles between checked and unchecked states. It supports separate images for checked, unchecked, hover, and disabled states, providing a visually rich alternative to standard checkboxes.

Original Ajax Control Toolkit documentation: https://www.asp.net/ajax/ajaxcontroltoolkit/ToggleButtonExtender

Features Supported in Blazor

TargetControlID — ID of the checkbox to enhance with toggle image behavior
ImageWidth — Width of the toggle image in pixels
ImageHeight — Height of the toggle image in pixels
UncheckedImageUrl — Image URL for the unchecked state
CheckedImageUrl — Image URL for the checked state
UncheckedImageAlternateText — Alt text for the unchecked image
CheckedImageAlternateText — Alt text for the checked image
CheckedImageOverUrl — Hover image URL when checked
UncheckedImageOverUrl — Hover image URL when unchecked
DisabledUncheckedImageUrl — Image URL when disabled and unchecked
DisabledCheckedImageUrl — Image URL when disabled and checked
Enabled — Enable or disable the extender behavior
BehaviorID — Optional identifier for JavaScript behavior lookup

Web Forms Syntax

<asp:CheckBox ID="chkSubscribe" runat="server" />

<ajaxToolkit:ToggleButtonExtender
    ID="tbe1"
    runat="server"
    TargetControlID="chkSubscribe"
    ImageWidth="24"
    ImageHeight="24"
    UncheckedImageUrl="~/images/toggle-off.png"
    CheckedImageUrl="~/images/toggle-on.png"
    UncheckedImageAlternateText="Not subscribed"
    CheckedImageAlternateText="Subscribed"
    CheckedImageOverUrl="~/images/toggle-on-hover.png"
    UncheckedImageOverUrl="~/images/toggle-off-hover.png" />

Blazor Migration

<CheckBox ID="chkSubscribe" />

<ToggleButtonExtender
    TargetControlID="chkSubscribe"
    ImageWidth="24"
    ImageHeight="24"
    UncheckedImageUrl="/images/toggle-off.png"
    CheckedImageUrl="/images/toggle-on.png"
    UncheckedImageAlternateText="Not subscribed"
    CheckedImageAlternateText="Subscribed"
    CheckedImageOverUrl="/images/toggle-on-hover.png"
    UncheckedImageOverUrl="/images/toggle-off-hover.png" />

Migration is simple: Remove the ajaxToolkit: prefix and runat="server". Update image paths from ~/ to /. Everything else stays the same!

Properties Reference

Property	Type	Default	Description
`TargetControlID`	`string`	(required)	ID of the checkbox to enhance with toggle image behavior
`ImageWidth`	`int`	`0`	Width of the toggle image in pixels
`ImageHeight`	`int`	`0`	Height of the toggle image in pixels
`UncheckedImageUrl`	`string`	`""`	URL of the image displayed when the checkbox is unchecked
`CheckedImageUrl`	`string`	`""`	URL of the image displayed when the checkbox is checked
`UncheckedImageAlternateText`	`string`	`""`	Alternate text for the unchecked image (accessibility)
`CheckedImageAlternateText`	`string`	`""`	Alternate text for the checked image (accessibility)
`CheckedImageOverUrl`	`string`	`""`	URL of the image displayed on hover when checked
`UncheckedImageOverUrl`	`string`	`""`	URL of the image displayed on hover when unchecked
`DisabledUncheckedImageUrl`	`string`	`""`	URL of the image displayed when disabled and unchecked
`DisabledCheckedImageUrl`	`string`	`""`	URL of the image displayed when disabled and checked
`BehaviorID`	`string`	TargetControlID	Optional identifier for JavaScript behavior lookup
`Enabled`	`bool`	`true`	Whether the extender is active

Usage Examples

Basic Toggle Button

@rendermode InteractiveServer

<CheckBox ID="chkNotifications" />

<ToggleButtonExtender
    TargetControlID="chkNotifications"
    ImageWidth="48"
    ImageHeight="24"
    UncheckedImageUrl="/images/switch-off.png"
    CheckedImageUrl="/images/switch-on.png"
    UncheckedImageAlternateText="Notifications off"
    CheckedImageAlternateText="Notifications on" />

Toggle with Hover States

@rendermode InteractiveServer

<CheckBox ID="chkFavorite" />

<ToggleButtonExtender
    TargetControlID="chkFavorite"
    ImageWidth="32"
    ImageHeight="32"
    UncheckedImageUrl="/images/star-empty.png"
    CheckedImageUrl="/images/star-filled.png"
    UncheckedImageOverUrl="/images/star-empty-hover.png"
    CheckedImageOverUrl="/images/star-filled-hover.png"
    UncheckedImageAlternateText="Add to favorites"
    CheckedImageAlternateText="Remove from favorites" />

Toggle with Disabled States

@rendermode InteractiveServer

<CheckBox ID="chkFeature" Enabled="false" />

<ToggleButtonExtender
    TargetControlID="chkFeature"
    ImageWidth="48"
    ImageHeight="24"
    UncheckedImageUrl="/images/toggle-off.png"
    CheckedImageUrl="/images/toggle-on.png"
    DisabledUncheckedImageUrl="/images/toggle-off-disabled.png"
    DisabledCheckedImageUrl="/images/toggle-on-disabled.png" />

HTML Output

The ToggleButtonExtender produces no HTML itself — it attaches JavaScript behavior that replaces the checkbox's visual appearance with an image element while preserving the checkbox's checked/unchecked state.

JavaScript Interop

The ToggleButtonExtender loads toggle-button-extender.js as an ES module. JavaScript handles:

Hiding the original checkbox and displaying an image in its place
Swapping images on click (checked ↔ unchecked)
Swapping images on hover (over states)
Displaying disabled images when the checkbox is disabled
Keeping the underlying checkbox state in sync

Render Mode Requirements

The ToggleButtonExtender requires InteractiveServer render mode:

@rendermode InteractiveServer

Graceful Degradation

SSR/Static mode: The extender silently skips initialization. The standard checkbox is displayed.
JavaScript disabled: Same as SSR — standard checkbox functions normally.

Migration Notes

From Web Forms Ajax Toolkit

Remove ajaxToolkit: prefix

- <ajaxToolkit:ToggleButtonExtender
+ <ToggleButtonExtender

Remove runat="server" and ID attributes

Update image paths from ~/ syntax to / paths

- UncheckedImageUrl="~/images/toggle-off.png"
+ UncheckedImageUrl="/images/toggle-off.png"

Before (Web Forms)

<asp:CheckBox ID="chkAgree" runat="server" />

<ajaxToolkit:ToggleButtonExtender
    ID="tbe1"
    TargetControlID="chkAgree"
    ImageWidth="24"
    ImageHeight="24"
    UncheckedImageUrl="~/images/unchecked.png"
    CheckedImageUrl="~/images/checked.png"
    runat="server" />

After (Blazor)

<CheckBox ID="chkAgree" />

<ToggleButtonExtender
    TargetControlID="chkAgree"
    ImageWidth="24"
    ImageHeight="24"
    UncheckedImageUrl="/images/unchecked.png"
    CheckedImageUrl="/images/checked.png" />

Best Practices

Always provide alt text — Set UncheckedImageAlternateText and CheckedImageAlternateText for accessibility
Use consistent image sizes — Set ImageWidth and ImageHeight to prevent layout shifts
Provide hover states — CheckedImageOverUrl and UncheckedImageOverUrl improve visual feedback
Include disabled states — If your checkbox can be disabled, provide DisabledCheckedImageUrl and DisabledUncheckedImageUrl
Optimize images — Use small, optimized PNG or SVG images for fast loading

Troubleshooting

Issue	Solution
Image not appearing	Verify `CheckedImageUrl` and `UncheckedImageUrl` point to valid image files. Ensure `@rendermode InteractiveServer` is set.
Standard checkbox still visible	Check that `TargetControlID` matches the checkbox's `ID` exactly.
Hover state not working	Verify `CheckedImageOverUrl` and `UncheckedImageOverUrl` paths are correct.
Toggle state not syncing	Ensure the target is a checkbox element. Check browser console for JavaScript errors.