Blazor Ramp - Switch

Name: BlazorRamp.Switch
Author: BlazorRamp.Switch

The Blazor Ramp project aims to provide a suite of modular, accessibility-first Blazor components.

The Switch is a simple toggle component that is either on or off communicated to assistive technologies via the use or the role="switch"" and the aria-checked attributed true or false for the on/off states.

Requirements

It is a requirement that the Blazor Ramp Core script, Live Region Service, and associated Announcement History component are added alongside this component’s specific requirements (a stylesheet reference), as outlined below.

Note: Every package includes a reference to the Blazor Ramp Core project (where the aforementioned items reside) so there is no need to install this package separately (but it can be if you only require the Live Regions Service and Announcement History component).

The full documentation is available at: https://docs.blazorramp.uk

Installation

Add the BlazorRamp.Switch nuget package to your project using the Nuget Package Manager or the dotnet CLI.

dotnet add package BlazorRamp.Switch

Add the following Core and Busy Indicator stylesheet references to the <head> section of your application:

Blazor Web App / Blazor Server → App.razor
Blazor WebAssembly → wwwroot/index.html

<head>
	<link rel="stylesheet" href="_content/BlazorRamp.Core/assets/css/core.min.css" />
	<link rel="stylesheet" href="_content/BlazorRamp.Switch/assets/css/switch.min.css" />
</head>

Add the following Blazor Ramp Core live region script after Blazors script, as follows:

Blazor Web App / Blazor Server → App.razor
Blazor WebAssembly → wwwroot/index.html

<script src="_framework/blazor.web.js"></script>
<script type="module" src="_content/BlazorRamp.Core/assets/js/core-live-region.js"></script>

Register BlazorRamp services in the Program.cs file (Both server and client if using Server and WebAssembly interactive rendermode)

Add the following line to the service registration section:

@using BlazorRamp.Core.Common.Extensions;

builder.Services.AddBlazorRampCore();

Add the <AnnouncementHistory /> component with your parameter values above the Router component contained in either:

Blazor Web App / Blazor Server → Routes.razor
Blazor WebAssembly → App.razor

<AnnouncementHistory RefreshText="Refresh" ClearCloseText="Clear & Close" CloseText="Close" NoDataText="No announcements" 
Title="Recent Announcements" TriggerVisible="true" TriggerText="Alerts" />

<Router AppAssembly . . .

Using the Switch

You can use either use the @bind:SwitchState for two-way binding or the event, EventCallbac<bool> with one-way binding. By default the switch and label will be together and aligned to the right of the parent container as below. Clicking on either the label or the switch with toggle it its state.

The example below uses the @bind-SwitchState="@_switchState" syntax to bind the switch state variable.

<Switch @bind-SwitchState="@_switchState" Label="Airplane mode:" AriaDisabled="@_switchDisabled" SpaceBetween="false" />

@code {

    private bool _switchState    = false;
    private bool _switchDisabled = false;
}

Note: In production, unlike the test you would use a variable for the AriaEndText and assign it with correct status dependant on success or failure.

If the user has their system settings for reduced motion instead of a spinning circle they will see a static hour gloss.

For the full description of all the component parameters and events, please see the documentation for the Busy Indicator: https://docs.blazorramp.uk/components/busy-indicator

Using the Live Region Service (directly)

Inject the ILiveRegionService into your desired component or class and make the appropriate calls by passing the ILiveRegionSerivce.MakeAnnouncement method an announcement object.

@inject ILiveRegionService _liveRegionService

@code{

	private async Task MakeAnnouncement()
	{
		var announcement = new Announcement("The site is now using a dark coloured theme.", AnnouncementType.Info, "Dark Theme Switch", LiveRegionType.Polite);
		await _liveRegionService.MakeAnnouncement(announcement);
	}
}

Note: Where possible make announcements using LiveRegionType.Polite and keep your messages brief and to the point. Long verbose messages are annoying and just slow the user down.

The announcement object has the following constructor parameters:

Message - a string value containing the message to be announced.
AnnouncementType - an enumerated type describing the type category of announcement (for future use) the default is AnnoucementType.Info,
AnnouncementTrigger - an optional string value with the user friendly display name of the element that triggered the announcement such as 'Save Button'
LiveRegionType - the urgency of the announcement. Polite announcements wait for the screen reader to finish current speech before announcing where as assertive announcements interrupt the screen reader immediately.

Full documentation available at: https://docs.blazorramp.uk

Screen Reader Browser Combination Tests:

On Windows 11 - JAWS, NVDA and Narrator each paired with Chrome, Edge and Firefox.
On macOS (Sequoia) VoiceOver was paired with Safari
On iPhone, VoiceOver was paired with Safari
On Android, TalkBack was paired with Chrome

Blazor Ramp - Switch

The Blazor Ramp project aims to provide a suite of modular, accessibility-first Blazor components.

Requirements

The full documentation is available at: https://docs.blazorramp.uk

Installation

Add the BlazorRamp.Switch nuget package to your project using the Nuget Package Manager or the dotnet CLI.

dotnet add package BlazorRamp.Switch

Add the following Core and Busy Indicator stylesheet references to the <head> section of your application:

Blazor Web App / Blazor Server → App.razor
Blazor WebAssembly → wwwroot/index.html

<head>
	<link rel="stylesheet" href="_content/BlazorRamp.Core/assets/css/core.min.css" />
	<link rel="stylesheet" href="_content/BlazorRamp.Switch/assets/css/switch.min.css" />
</head>

Add the following Blazor Ramp Core live region script after Blazors script, as follows:

Blazor Web App / Blazor Server → App.razor
Blazor WebAssembly → wwwroot/index.html

<script src="_framework/blazor.web.js"></script>
<script type="module" src="_content/BlazorRamp.Core/assets/js/core-live-region.js"></script>

Register BlazorRamp services in the Program.cs file (Both server and client if using Server and WebAssembly interactive rendermode)

Add the following line to the service registration section:

@using BlazorRamp.Core.Common.Extensions;

builder.Services.AddBlazorRampCore();

Add the <AnnouncementHistory /> component with your parameter values above the Router component contained in either:

Blazor Web App / Blazor Server → Routes.razor
Blazor WebAssembly → App.razor

<AnnouncementHistory RefreshText="Refresh" ClearCloseText="Clear & Close" CloseText="Close" NoDataText="No announcements" 
Title="Recent Announcements" TriggerVisible="true" TriggerText="Alerts" />

<Router AppAssembly . . .

Using the Switch

The example below uses the @bind-SwitchState="@_switchState" syntax to bind the switch state variable.

<Switch @bind-SwitchState="@_switchState" Label="Airplane mode:" AriaDisabled="@_switchDisabled" SpaceBetween="false" />

@code {

    private bool _switchState    = false;
    private bool _switchDisabled = false;
}

Note: In production, unlike the test you would use a variable for the AriaEndText and assign it with correct status dependant on success or failure.

If the user has their system settings for reduced motion instead of a spinning circle they will see a static hour gloss.

For the full description of all the component parameters and events, please see the documentation for the Busy Indicator: https://docs.blazorramp.uk/components/busy-indicator

Using the Live Region Service (directly)

Inject the ILiveRegionService into your desired component or class and make the appropriate calls by passing the ILiveRegionSerivce.MakeAnnouncement method an announcement object.

@inject ILiveRegionService _liveRegionService

@code{

	private async Task MakeAnnouncement()
	{
		var announcement = new Announcement("The site is now using a dark coloured theme.", AnnouncementType.Info, "Dark Theme Switch", LiveRegionType.Polite);
		await _liveRegionService.MakeAnnouncement(announcement);
	}
}

Note: Where possible make announcements using LiveRegionType.Polite and keep your messages brief and to the point. Long verbose messages are annoying and just slow the user down.

The announcement object has the following constructor parameters:

Message - a string value containing the message to be announced.
AnnouncementType - an enumerated type describing the type category of announcement (for future use) the default is AnnoucementType.Info,
AnnouncementTrigger - an optional string value with the user friendly display name of the element that triggered the announcement such as 'Save Button'
LiveRegionType - the urgency of the announcement. Polite announcements wait for the screen reader to finish current speech before announcing where as assertive announcements interrupt the screen reader immediately.

Full documentation available at: https://docs.blazorramp.uk

Screen Reader Browser Combination Tests:

On Windows 11 - JAWS, NVDA and Narrator each paired with Chrome, Edge and Firefox.
On macOS (Sequoia) VoiceOver was paired with Safari
On iPhone, VoiceOver was paired with Safari
On Android, TalkBack was paired with Chrome

code-dispenser/BlazorRamp.Switchv1.0.0

Get Started

Readme

Blazor Ramp - Switch

Requirements

Installation

Using the Switch

Using the Live Region Service (directly)

code-dispenser/BlazorRamp.Switchv1.0.0

Get Started

Readme

Blazor Ramp - Switch

Requirements

Installation

Using the Switch

Using the Live Region Service (directly)