Skip to content

Commit db7101f

Browse files
ntachevadimodi
andauthored
docs(switch): Revamp Overview (#1055)
* docs(switch): Revamp Overview * docs(switch): update * Update components/switch/overview.md Co-authored-by: Dimo Dimov <[email protected]> * Update components/switch/overview.md Co-authored-by: Dimo Dimov <[email protected]> * docs(switch):address feedback * docs(switch):minor fixes Co-authored-by: Dimo Dimov <[email protected]>
1 parent 2b3dac0 commit db7101f

File tree

2 files changed

+107
-86
lines changed

2 files changed

+107
-86
lines changed

components/switch/labels.md

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
title: Labels
3+
page_title: Switch Labels
4+
description: Labels in the Switch for Blazor.
5+
slug: switch-labels
6+
tags: telerik,blazor,labels,on,off
7+
published: True
8+
position: 10
9+
---
10+
11+
# Switch Labels
12+
13+
`On` or `Off` labels are rendered inside the Switch based on its value:
14+
15+
* `OnLabel` will be shown when the Switch `Value` is `true`
16+
* `OffLabel` will be shown when the Switch `Value` is `false`
17+
18+
The component allows customization of the labels text through the dedicated parameters. [Provide your desired strings](#customize-labels-text) for the Switch labels or [use a blank space to remove visible labels](#remove-labels).
19+
20+
## Customize Labels Text
21+
22+
Provide the desired text for the On and Off labels through the corresponding parameters. If the text is longer, you can increase the component `Width` to ensure the label will be visible.
23+
24+
````CSHTML
25+
@* Use the OnLabel and OffLabel to customize the labels of the Switch. Use the Width parameter to manipulate the width of the component. *@
26+
<p>
27+
I agree to the terms and conditions
28+
</p>
29+
30+
<TelerikSwitch @bind-Value="@hasAgreed"
31+
OnLabel="@myOnLabel"
32+
OffLabel="@myOffLabel"
33+
Width="100px">
34+
</TelerikSwitch>
35+
36+
@code {
37+
public bool hasAgreed { get; set; }
38+
public string myOnLabel { get; set; } = "Agree";
39+
public string myOffLabel { get; set; } = "Disagree";
40+
}
41+
````
42+
43+
## Remove Labels
44+
45+
To remove the Switch labels, use a blank space for the `OnLabel` and `OffLabel` parameters.
46+
47+
````CSHTML
48+
@* Use a blank space to remove visible labels *@
49+
50+
<TelerikSwitch @bind-Value="@isSelected" OnLabel=" " OffLabel=" " />
51+
52+
@code {
53+
private bool isSelected { get; set; }
54+
}
55+
````
56+
57+
## See Also
58+
* [Live Demo: Switch Labels](https://demos.telerik.com/blazor-ui/switch/labels)
59+
* [Switch Events]({%slug switch-events%})

components/switch/overview.md

Lines changed: 48 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,10 @@ position: 0
1212

1313
The <a href = "https://www.telerik.com/blazor-ui/switch" target="_blank">Blazor Switch component</a> allows the user to toggle between checked and unchecked states.
1414

15-
#### To use a Telerik Switch for Blazor
15+
## Creating Blazor Switch
1616

17-
1. add the `TelerikSwitch` tag
18-
1. provide `Value` (one-way data binding) or `bind-Value` (two-way data binding) property
17+
1. Use the `<TelerikSwitch>` tag
18+
1. Provide a `Value` (one-way binding) or `@bind-Value` (two-way binding)
1919

2020

2121
>caption Basic setup of the Telerik Switch using two-way data binding
@@ -37,118 +37,80 @@ The <a href = "https://www.telerik.com/blazor-ui/switch" target="_blank">Blazor
3737
3838
![Telerik Switch Component](images/swtich-first-look.gif)
3939

40-
## Features
40+
## Labels
4141

42-
The Switch provides the following features:
42+
The Switch has dedicated `On` and `Off` labels serving as text representation of the component value. [Read more about the Switch labels....]({%slug switch-labels%})
4343

44-
* `Class` - the CSS class that will be rendered on the main wrapping element of the Switch. Use it to [customize the Switch background color and other styles]({%slug switch-kb-change-background-color%})
44+
## Events
4545

46-
* `Enabled` - whether the component is enabled.
46+
The Blazor Switch generates events that you can handle and further customize its behavior. [Read more about the Switch events....]({%slug switch-events%})
4747

48-
* `Id` - renders as the `id` attribute on the wrapping `<span>` element of the component.
48+
## Validation
4949

50-
* `Width` - the width of the component.
50+
You can ensure that the component value is acceptable by using the built-in validation. [Read more about input validation....]({%slug common-features/input-validation%})
5151

52-
* `TabIndex` - the `tabindex` attribute rendered on the Switch.
52+
## Switch Parameters
5353

54-
* `Value` and `bind-Value` - accept `bool` and `bool?` data types.
54+
The following table lists the Switch parameters. Also check the [Switch API Reference](/blazor-ui/api/Telerik.Blazor.Components.TelerikSwitch-1) for a full list of all properties, methods and events.
5555

56-
* `OnLabel` - the label of the component when the `Value` is `true`.
56+
@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)
5757

58-
* `OffLabel` - the label of the component when the `Value` is `false`.
58+
| Attribute | Type and Default Value | Description |
59+
|----------|----------|----------|
60+
| `Enabled` | `bool` | Whether the component is enabled.
61+
| `Id` | `string` | Renders as the `id` attribute on the wrapping `<span>` element of the component.
62+
| `TabIndex` | `int` | The `tabindex` attribute rendered on the Switch.
63+
| `Value` | `bool` or `bool?`| The value of the Switch. Supports two-way binding.
64+
| `OnLabel` | `string` | The label of the component when the `Value` is `true`.
65+
| `OffLabel` | `string` | The label of the component when the `Value` is `false`.
5966

60-
* Events - see the [Switch events]({%slug switch-events%}) article for more information and examples.
67+
### Styling and Appearance
6168

62-
* Validation - see the [Input Validation]({%slug common-features/input-validation%}) article for more details.
69+
The following parameters enable you to customize the appearance of the Blazor Switch:
6370

64-
## Component Reference
71+
@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)
6572

66-
The Switch is a generic component and its type comes from the model field it is bound to - it is either `bool` or `bool?` (a `null` value is treated as `false`).
73+
| Attribute | Type and Default Value | Description |
74+
|----------|----------|----------|
75+
| `Class` | `string` | The CSS class that will be rendered on the main wrapping element of the Switch. Use it to [customize the Switch background color and other styles]({%slug switch-kb-change-background-color%})
76+
| `Width` | `string` | The width of the component. You can set the Width parameter to any of the [supported units]({%slug common-features/dimensions%}).
6777

68-
>caption Switch Reference
78+
You can find more options for customizing the Switch styling in the [Appearance article]({%slug switch-appearance%}).
6979

70-
````CSHTML
71-
@* The Switch reference type comes from its Value type *@
72-
73-
<TelerikSwitch @bind-Value="@toggleSwitch" @ref="@TheSwitchRef" />
74-
75-
@code{
76-
bool toggleSwitch { get; set; } // the type of this field determines the type of the reference
77-
TelerikSwitch<bool> TheSwitchRef { get; set; }
78-
}
79-
````
80-
81-
## Examples
82-
83-
This section shows the following two examples
84-
85-
* [Remove Labels](#remove-labels)
86-
* [Custom Labels and Size](#custom-labels-and-size)
87-
88-
89-
### Remove Labels
90-
91-
>caption Switch without labels
92-
93-
````CSHTML
94-
@* Use a blank space to remove visible labels *@
80+
## Switch Reference and Methods
9581

96-
<TelerikSwitch @bind-Value="@isSelected" OnLabel=" " OffLabel=" " />
82+
The Switch is a generic component and its type comes from the model field it is bound to - it is either `bool` or `bool?` (a `null` value is treated as `false`). Add a reference to the component instance to use the [Switch methods](https://docs.telerik.com/blazor-ui/api/Telerik.Blazor.Components.TelerikSwitch-1#methods).
9783

98-
@code {
99-
private bool isSelected { get; set; }
100-
}
101-
````
102-
103-
### Custom Labels and Size
104-
105-
The example below shows how to:
106-
107-
* Bind the switch to a value
108-
* Set custom labels for its On and Off states
109-
* Use the `Width` parameter to control the size of the component
84+
@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)
11085

111-
>caption Example that showcases the "I agree to the terms and conditions" basic scenario
86+
| Method | Description |
87+
| --- | --- |
88+
| `FocusAsync ` | programmatically focuses the Switch.
11289

11390
````CSHTML
114-
@* Use the OnLabel and OffLabel to customize the labels of the Switch. Use the Width parameter to manipulate the width of the component. *@
91+
@* Use the Switch reference to programmatically focus the component *@
11592
116-
<h2 class="text-info">Terms and conditions</h2>
93+
<TelerikButton OnClick="@FocusSwitch">Focus Switch</TelerikButton>
11794
118-
@if (hasAgreed)
119-
{
120-
<div class="alert alert-success w-50">
121-
Thank you for agreeing to our terms and conditions!
122-
</div>
123-
}
124-
else
125-
{
126-
<p class="w-50 text-justify">
127-
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris mi lectus, ultrices sed libero et, tempor rutrum mauris. Praesent sit amet suscipit leo, ut hendrerit lacus. Mauris posuere, mi in elementum pretium, sem elit maximus mauris, ac tempus turpis nunc sed orci. Nunc velit lacus, rutrum et dui mattis, condimentum fermentum velit. Pellentesque et elit rhoncus, sodales nibh ac, faucibus tellus. Vestibulum vitae tempor tellus. Sed maximus sem quis est posuere, efficitur porttitor augue tincidunt. Sed viverra dapibus ullamcorper. Vestibulum ex arcu, molestie sed quam vulputate, aliquet cursus lectus. Aenean sollicitudin condimentum fringilla. Integer arcu justo, sollicitudin ut libero ut, posuere finibus sapien. Suspendisse hendrerit convallis urna.
128-
Donec eu sodales dui, et consequat massa. Integer vitae euismod dui, id rhoncus tellus. Ut luctus leo eget sapien eleifend facilisis. Duis sed maximus tortor. Ut nunc nibh, pulvinar a enim eget, mattis sagittis sem. Mauris odio nibh, aliquet a erat sit amet.
129-
</p>
130-
}
131-
132-
<TelerikSwitch @bind-Value="@hasAgreed"
133-
Id="mySwitch"
134-
OnLabel="@myOnLabel"
135-
OffLabel="@myOffLabel"
136-
Width="100px">
137-
</TelerikSwitch>
138-
I agree to the terms and conditions
95+
<TelerikSwitch @bind-Value="@toggleSwitch" @ref="@SwitchRef" />
13996
14097
@code {
141-
public bool hasAgreed { get; set; }
142-
public string myOnLabel { get; set; } = "Agree";
143-
public string myOffLabel { get; set; } = "Disagree";
98+
bool toggleSwitch { get; set; } // the type of this field determines the type of the reference
99+
TelerikSwitch<bool> SwitchRef { get; set; }
100+
101+
void FocusSwitch()
102+
{
103+
SwitchRef.FocusAsync();
104+
}
144105
}
145106
````
146-
>caption The result from the code snippet above
147107

148-
![agree to terms and conditions](images/switch-terms-and-conditions-example.gif)
108+
## Next Steps
149109

110+
* [Customize the Switch labels]({%slug switch-labels%})
111+
* [Handle the Switch events]({%slug switch-events%})
150112

151113
## See Also
152114
* [Live Demo: Switch](https://demos.telerik.com/blazor-ui/switch/overview)
153115
* [Switch Events]({%slug switch-events%})
154-
116+
* [Switch API Reference](/blazor-ui/api/Telerik.Blazor.Components.TelerikSwitch-1)

0 commit comments

Comments
 (0)