> For the complete documentation index, see [llms.txt](https://docs-siticoneframework.gitbook.io/home/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-siticoneframework.gitbook.io/home/net-framework-or-net-core-ui/input-controls/siticone-togglebutton/accessibility.md).

# Accessibility

Provides a custom accessible object that improves compatibility with screen readers and other accessibility tools, enhancing the usability of the Siticone ToggleButton for all users.

## **Overview**

The **Accessibility** feature ensures that the `SiticoneToggleButton` is recognized appropriately by assistive technologies (e.g., screen readers). By customizing the control’s accessible object, the toggle’s role is identified as a **push button**, and its checked state is communicated via accessibility properties. This means users relying on screen readers can perceive and interact with the control effectively.

***

### **Key API Members**

Below is a table summarizing how accessibility is implemented within the control:

| **Method / Class**                     | **Type**                           | **Description**                                                                                                                                                 |
| -------------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **CreateAccessibilityInstance()**      | `protected override` method        | Instantiates and returns a `CustomToggleButtonAccessibleObject`, which extends `ControlAccessibleObject` for more detailed accessibility.                       |
| **CustomToggleButtonAccessibleObject** | `ControlAccessibleObject` subclass | A specialized accessible class that overrides properties such as `Name`, `Role`, and `State` to accurately communicate toggle status to assistive technologies. |

Within `CustomToggleButtonAccessibleObject`:

| **Property** | **Override From**         | **Behavior**                                                                                                 |
| ------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Name**     | `ControlAccessibleObject` | Returns the toggle control’s current `Text`. This is what screen readers announce for the control.           |
| **Role**     | `ControlAccessibleObject` | Set to `AccessibleRole.PushButton`, indicating the control can be pressed like a button.                     |
| **State**    | `ControlAccessibleObject` | Adds `AccessibleStates.Checked` if `IsToggled` is true, letting screen readers know the toggle is “checked.” |

***

### **Key Points to Note**

1. **Screen Readers Recognize the Toggle as a Push Button**
   * The `AccessibleRole` is `PushButton`, helping screen readers interpret the control as an interactive button rather than a static element.
2. **Checked State Information**
   * When `IsToggled` is true, the control sets the accessible state to include `Checked`, so assistive tools announce the toggle as checked/on.
3. **Name Synchronization**
   * The accessible object’s `Name` property returns the control’s `Text`, which typically aligns with the control’s displayed text.
   * Developers should ensure that the text property reflects a meaningful label (e.g., “Enable Notifications”) to clarify the toggle’s purpose.
4. **No Additional Configuration Required**
   * This accessibility support is **built-in**. Simply use the control as normal, and it will be recognized appropriately by most assistive technologies.

***

### **Usage Example**

```csharp
// Basic usage doesn't require extra steps for accessibility.
// However, to make the accessibility information more descriptive, set 'Text' meaningfully:

myToggle.Text = "Enable Feature X";

// Optionally, if you want to confirm how accessibility is exposed:
Console.WriteLine(myToggle.AccessibilityObject.Name);    // "Enable Feature X"
Console.WriteLine(myToggle.AccessibilityObject.Role);    // PushButton
// If the toggle is currently on:
Console.WriteLine(myToggle.AccessibilityObject.State);   // Focusable, Focused, Checked, etc.
```

> **Tip:** Always ensure the control’s `Text` accurately reflects the toggle’s function or label.

***

### **Best Practices to Create Beautiful UI and Apps**

| **Practice**                                                                          | **Reason**                                                                                               |
| ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Use **meaningful text** for the toggle’s `Text` or `ToggledText` and `UntoggledText`. | This text is announced by screen readers, so it must clearly describe the control’s purpose.             |
| Keep **toggle text** concise but descriptive.                                         | Ensures a balance between clarity for sighted users and effective announcements for screen reader users. |
| Test your application with **common screen readers** (e.g., NVDA, JAWS).              | Verifies that the accessible object properties (Name, Role, State) are read out as expected.             |
| Update **Text** consistently if you programmatically change the control’s function.   | Users relying on assistive technologies need accurate labeling at all times.                             |

***

### **Common Pitfalls and Design Considerations**

| **Pitfall**                                                                                                            | **Mitigation / Recommendation**                                                                                                       |
| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Leaving the toggle’s `Text` blank or irrelevant.                                                                       | Provide a short but clear description of the toggle’s purpose.                                                                        |
| Confusion between **ToggledText** and **Text** for accessibility naming.                                               | The accessible `Name` property specifically refers to the `Text` property, not the toggled/off text strings.                          |
| Expecting the control to provide full **accessibility for advanced scenarios** (e.g., dynamic text changes on events). | If the control’s functionality changes drastically, ensure to update its `Text` property or implement additional accessibility logic. |

***

### **Review and Summary**

* **What You Learned**:\
  How `SiticoneToggleButton` leverages a **custom accessible object** to enhance screen reader compatibility, communicating “checked” state and a meaningful name.
* **Why It’s Important**:\
  Inclusive design is crucial—ensuring users of assistive technologies can interact with toggles as effectively as sighted users fosters a broader user base.
* **How to Move Forward**:\
  Continue providing well-labeled text, test your UI with accessibility tools, and combine these best practices with other features (e.g., animations or read-only states) to create an app that’s both powerful and accessible.

By using **Accessibility** features built into `SiticoneToggleButton`, you ensure a more inclusive and user-friendly experience, aligning your application with modern standards and a commitment to universal usability.