Skip to content

Commit 94e98ce

Browse files
dimodiDimo Dimov
dimodi
and
Dimo Dimov
authored
[3.1] docs: Add FloatingLabel documentation (#809)
* docs: Add FloatingLabel documentation * Add supporting information for FloatingLabel * Add supporting information for FloatingLabel 2 * Add supporting information for FloatingLabel 3 * Add supporting information for FloatingLabel 4 Co-authored-by: Dimo Dimov <[email protected]>
1 parent 08b438a commit 94e98ce

File tree

5 files changed

+212
-15
lines changed

5 files changed

+212
-15
lines changed

‎_config.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -312,6 +312,8 @@ navigation:
312312
title: "Form"
313313
"*flatcolorpicker":
314314
title: "FlatColorPicker"
315+
"*floatinglabel":
316+
title: "FloatingLabel"
315317
"*gantt":
316318
title: "Gantt"
317319
"*gauges":

‎components/floatinglabel/overview.md

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
---
2+
title: Overview
3+
page_title: FloatLabel Overview
4+
description: Overview of the FloatingLabel for Blazor and its features. What is a floating label and how to use it.
5+
slug: floatinglabel-overview
6+
tags: telerik,blazor,floatinglabel,floating,label,overview
7+
published: True
8+
position: 0
9+
---
10+
11+
# Blazor Floating Label Overview
12+
13+
The <a href="https://www.telerik.com/blazor-ui/floatinglabel" target="_blank">Blazor FloatingLabel component</a> provides additional features and improved user experience, compared to the standard HTML `label`. The floating label displays on top of empty non-focused components and moves above them on focus.
14+
15+
16+
## Benefits
17+
18+
The Telerik FloatingLabel enhances HTML `label` functionality in the following ways:
19+
20+
* built-in animations
21+
* integration with form validation
22+
* integration with the `placeholder` attribute
23+
* association with non-form elements - for example, the TelerikDropDownList component renders as a `<span>`
24+
25+
26+
## Creating Blazor FloatingLabel
27+
28+
1. Use the `TelerikFloatingLabel` tag.
29+
1. Set the `Text` parameter of the floating label.
30+
1. Place a [compatible Telerik component](#compatibility) inside the floating label.
31+
1. Set an `Id` to the Telerik component. The `Id` value will automatically render as a `for` attribute for the `<label>` element.
32+
33+
>caption How to use a Floating Label
34+
35+
````CSHTML
36+
<TelerikFloatingLabel Text="Your Name">
37+
<TelerikTextBox Id="name" @bind-Value="@Name" />
38+
</TelerikFloatingLabel>
39+
40+
@code {
41+
string Name { get; set; }
42+
}
43+
````
44+
45+
46+
## Compatibility
47+
48+
The FloatingLabel integrates with focusable Telerik Blazor components:
49+
50+
* AutoComplete
51+
* ComboBox
52+
* DateInput
53+
* DatePicker
54+
* DateTimePicker
55+
* DropDownList
56+
* MaskedTextBox
57+
* MultiSelect
58+
* NumericTextBox
59+
* TextArea
60+
* TextBox
61+
* TimePicker
62+
63+
The FloatingLabel does not support third-party components and generic HTML inputs.
64+
65+
66+
## Forms and Validation
67+
68+
The FloatingLabel can change its styles, based on validation state. See [Validation]({%slug floatinglabel-validation%}) for details and example.
69+
70+
71+
## Placeholder Behavior
72+
73+
Labels and placeholders serve similar purpose for the user experience.
74+
75+
If a Telerik component has both a `Placeholder` and a floating label, the behavior is:
76+
77+
* When the floating label is **over the component**, then the placeholder is **not rendered**.
78+
* When the floating label is **outside the component** and the focused component has no value, the placeholder **is visible**.
79+
80+
81+
## FloatingLabel Parameters
82+
83+
The following table lists the FloatingLabel parameters. Also check the [FloatingLabel API Reference](https://docs.telerik.com/blazor-ui/api/Telerik.Blazor.Components.TelerikFloatingLabel) for a full list of properties, methods and events.
84+
85+
<style>
86+
article style + table {
87+
table-layout: auto;
88+
word-break: normal;
89+
}
90+
</style>
91+
92+
| Attribute | Type | Description |
93+
| --- | --- | --- |
94+
| `Class` | `string` | Renders additional CSS class to the `span.k-floating-label-container` element, which holds the `<label>` child element. Use `Class` to apply custom styles or [override the theme]({%slug themes-override%}). |
95+
| `Id` | `string` | Renders an `id` attribute to the `label.k-label` element. To improve accessibility, set the same string as floating label `Id` and `AriaLabelledBy` value of the associated Telerik component. |
96+
97+
98+
## Next Steps
99+
100+
* [Review Floating Label integration with form validation]({%slug floatinglabel-validation%})
101+
102+
103+
## See Also
104+
105+
* [Live Floating Label Demos](https://demos.telerik.com/blazor-ui/floatinglabel/index)
106+
* [Floating Label API Reference](https://docs.telerik.com/blazor-ui/api/Telerik.Blazor.Components.TelerikFloatingLabel)

‎components/floatinglabel/validation.md

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
title: Validation
3+
page_title: FloatingLabel Validation
4+
description: The FloatingLabel can change its styling when it is inside a validated form and the associated form field is invalid. How to integrate the Blazor floating label with form validation.
5+
slug: floatinglabel-validation
6+
tags: telerik,blazor,floatinglabel,floating,label,form,validation
7+
published: True
8+
position: 10
9+
---
10+
11+
# Floating Label Validation
12+
13+
The Blazor FloatingLabel integrates with form validation of [compatible Telerik components]({%slug floatinglabel-overview%}#compatibility). When a form field is invalid, the floating label will change color to suggest user action.
14+
15+
>caption Floating Label Integration with Forms and Validation
16+
17+
````CSHTML
18+
@using System.ComponentModel.DataAnnotations
19+
20+
@if (ValidSubmit)
21+
{
22+
<p>The form was submitted successfully.</p>
23+
}
24+
else
25+
{
26+
<EditForm Model="@TestUser"
27+
OnValidSubmit="@HandleValidSubmit">
28+
<DataAnnotationsValidator />
29+
<TelerikValidationSummary />
30+
31+
<div>
32+
<TelerikFloatingLabel Text="Username *">
33+
<TelerikTextBox @bind-Value="@TestUser.Username" />
34+
</TelerikFloatingLabel>
35+
</div>
36+
37+
<div>
38+
<TelerikFloatingLabel Text="Password *">
39+
<TelerikTextBox @bind-Value="@TestUser.Password" Password="true" />
40+
</TelerikFloatingLabel>
41+
</div>
42+
43+
<p>
44+
<TelerikButton ButtonType="@ButtonType.Submit">Submit</TelerikButton>
45+
</p>
46+
</EditForm>
47+
}
48+
49+
@code {
50+
User TestUser { get; set; } = new User();
51+
52+
bool ValidSubmit { get; set; }
53+
54+
async void HandleValidSubmit()
55+
{
56+
ValidSubmit = true;
57+
58+
await Task.Delay(2000);
59+
60+
ValidSubmit = false;
61+
TestUser = new User();
62+
63+
StateHasChanged();
64+
}
65+
66+
public class User
67+
{
68+
[Display(Name = "Username")]
69+
[Required(ErrorMessage = "Username is required")]
70+
public string Username { get; set; }
71+
72+
[Display(Name = "Password")]
73+
[MinLength(8, ErrorMessage = "Password should be at least 8 characters")]
74+
[Required(ErrorMessage = "Password is required")]
75+
public string Password { get; set; }
76+
}
77+
}
78+
````
79+
80+
81+
## See Also
82+
83+
* [FloatingLabel Overview]({%slug floatinglabel-overview%})

‎knowledge-base/inputs-floating-label.md

Lines changed: 20 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -11,16 +11,21 @@ res_type: kb
1111

1212
## Environment
1313
<table>
14-
<tbody>
15-
<tr>
16-
<td>Product</td>
17-
<td>TextBox for Blazor, MaskedTextBox for Blazor, NumericTextBox for Blazor, other inputs/form elements</td>
18-
</tr>
19-
<tr>
20-
<td>Version</td>
21-
<td>3.0.0 and later before 3.2.0</td>
22-
</tr>
23-
</tbody>
14+
<tbody>
15+
<tr>
16+
<td>Product</td>
17+
<td>
18+
TextBox for Blazor, <br />
19+
MaskedTextBox for Blazor, <br />
20+
NumericTextBox for Blazor, <br />
21+
other inputs/form elements
22+
</td>
23+
</tr>
24+
<tr>
25+
<td>Version</td>
26+
<td>3.0.0 and 3.0.1</td>
27+
</tr>
28+
</tbody>
2429
</table>
2530

2631

@@ -30,9 +35,11 @@ I would like to show a floating label for Telerik Inputs. The label should be di
3035

3136
## Solution
3237

33-
>important The 3.0.0 release introduced a breaking change of removing the `Label` parameter from TextBox, MaskedTextBox, TextArea components. In 3.2.0 Floating Label component will be released to fulfill all use cases. However, in the meantime this solution can be used to implement floating label in any component.
38+
>important **UI for Blazor 3.1.0** includes a standalone [FloatingLabel component]({%slug floatinglabel-overview%}). Use that instead.
3439
35-
The following code snippet shows how to add a floating label to TextBox, MaskedTextBox, TextArea, DatePicker, and DropDownList components. The example illustrates how with simple html rendering that is shipped with `Telerik UI for Blazor` you could transform the inner html label into a floating label.
40+
The following code snippet shows how to add a floating label to TextBox, MaskedTextBox, TextArea, DatePicker, and DropDownList components. The example uses plain HTML elements and CSS styles that are included in the `Telerik UI for Blazor` theme. The styles transform the `<label>` element to a floating label.
41+
42+
>caption Implement a floating label with static HTML
3643
3744
````CSHTML
3845
<div style="width: 400px;">
@@ -82,5 +89,4 @@ The following code snippet shows how to add a floating label to TextBox, MaskedT
8289
public string DropDownListEmptyClass => string.IsNullOrEmpty(DropDownListValue) ? emptyClass : string.Empty;
8390
public List<string> DropDownListData { get; set; } = new List<string>() { "one", "two", "three" };
8491
}
85-
86-
````
92+
````

‎upgrade/breaking-changes/3-0-0.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -314,7 +314,7 @@ async Task OnGridStateInit(GridStateEventArgs&lt;GridModel&gt; args)
314314
</tbody>
315315
</table>
316316

317-
- **TextBox**, **MaskedTextBox**, **TextArea** - `Label` parameter is removed. In 3.2.0 release we will release standalone Floating Label component. In the meantime, you can use the following [KB that shows how to add the label]({%slug inputs-kb-floating-label %}).
317+
- **TextBox**, **MaskedTextBox**, **TextArea** - `Label` parameter is removed. UI for Blazor **3.1.0** features a standalone [FloatingLabel component]({%slug floatinglabel-overview%}). For UI for Blazor **3.0.0** and **3.0.1**, check the following [KB that shows how to add a label]({%slug inputs-kb-floating-label %}).
318318
- **TileLayout** - introduced optional `Id` attribute for the `TileLayoutItem`. The `OnResize` event handler will receive argument of type `TileLayoutResizeEventArgs`. The `OnReorder` event handler will receive argument of type `TileLayoutReorderEventArgs`. Both event arguments will point to the tile item (`args.Id`) and define if the component should re-render after the event (`args.ShouldRender`).
319319

320320
>caption TileLayout resize and reoder events in UI for Blazor up to version 2.30 and after version 3.0

0 commit comments

Comments
 (0)