diff --git a/_contentTemplates/common/inputs.md b/_contentTemplates/common/inputs.md index 784f2362cb..de10f46bae 100644 --- a/_contentTemplates/common/inputs.md +++ b/_contentTemplates/common/inputs.md @@ -7,3 +7,36 @@ Also check the dedicated KB article about [programmatic input component focusing Consider setting `DebounceDelay="0"` to the component inside the editor template. This is how the default editors in all Telerik Blazor components work. Otherwise, fast users may try to save changes before the data item in edit mode receives the new value. #end + +#adornments +## Adornments + +The component allows you to add custom elements as prefixes and suffixes. [Read more about how to render custom adornments before and after the input element...]({%slug common-features/input-adornments%}) +#end + +#floating-label-and-preffix +When using the [`PrefixTemplate`]({%slug common-features/input-adornments%}#adding-prefix-in-ui-for-blazor-components) for a component wrapped in a [FloatingLabel]({%slug floatinglabel-overview%}), the label will overlap the prefix. + +To ensure both the FloatingLabel and the prefix content are properly displayed, move the label with CSS: + +````CSHTML + + + + + + + + + + +@code{ + public string TextValue { get; set; } +} +```` +#end \ No newline at end of file diff --git a/common-features/dimensions.md b/common-features/dimensions.md index 7b1c6c9f19..4709439edc 100644 --- a/common-features/dimensions.md +++ b/common-features/dimensions.md @@ -5,7 +5,7 @@ description: How dimensions work and are set in the Telerik UI for Blazor compon slug: common-features/dimensions tags: telerik,blazor,dimensions,width,height,percent,pixel published: True -position: 3 +position: 7 --- # Dimensions diff --git a/common-features/input-adornments.md b/common-features/input-adornments.md new file mode 100644 index 0000000000..da804b09c6 --- /dev/null +++ b/common-features/input-adornments.md @@ -0,0 +1,416 @@ +--- +title: Input Adornments +page_title: Input Adornments +description: How to add prefix and suffix adornments in the input elements of the components. +slug: common-features/input-adornments +tags: telerik,blazor,input,adornments,prefix,suffix +published: True +position: 2 +--- + +# Input Adornments + +Telerik UI for Blazor supports adornments for some of the components that incorporate input element. Using adornments allows you to enhance the Telerik UI for Blazor components by adding custom prefix and suffix elements. + +A prefix input adornment refers to an element placed before the user input field. You may use it to provide clarity on the expected data in the input such as currency symbols or unit indicators. Conversely, a suffix input adornment is an element positioned after the user input field. It often serves to provide direct functionality for the entered data like password visibility toggles, formatting or clearing the input. + +>caption In this article: + +* [Supported Components](#supported-components) +* [Adding a Prefix Adornment](#adding-a-prefix-adornment) +* [Adding a Suffix Adornment](#adding-a-suffix-adornment) +* [Using Separators](#using-separators) +* [TextArea Specifics](#textarea-specifics) +* [FloatingLabel Specifics](#floatinglabel-specifics) +* [DropDowns Specifics](#dropdowns-specifics) + + +## Supported Components + +The following input components support prefix and suffix adornments: + +* [AutoComplete]({%slug autocomplete-overview%}) +* [ComboBox]({%slug components/combobox/overview%}) +* [MaskedTextbox]({%slug maskedtextbox-overview%}) +* [MultiColumnComboBox]({%slug multicolumncombobox-overview%}) +* [MultiSelect]({%slug multiselect-overview%}) +* [NumericTextBox]({%slug components/numerictextbox/overview%}) +* [TextArea]({%slug textarea-overview%}) +* [TextBox]({%slug components/textbox/overview%}) + +## Adding a Prefix Adornment + +To add a prefix, declare a `<*ComponentName*PrefixTemplate>` tag as a direct child of the `` tag. The `PrefixTemplate` is a `RenderFragment`, which allows you to declare any desired content as a prefix—simple text, HTML elements, or components. + + +>caption Adding a prefix adornment in UI for Blazor + +````CSHTML +
+
TextArea
+ + + + + + +
+ +
+
TextBox
+ + + + + + +
+ +
+
MaskedTextBox
+ + + + + + +
+ +
+
NumericTextBox
+ + + + m + + +
+ +
+
AutoComplete
+ + + + + + +
+ +
+
ComboBox
+ + + + + + +
+ +
+
MultiColumnComboBox
+ + + + + + + + + + +
+ +
+
MultiSelect
+ + + + + + +
+ +@code { + private string TextValue { get; set; } + private string SelectedProduct { get; set; } + private int SelectedProductId { get; set; } + private int Height { get; set; } + + private List Products = Enumerable.Range(1, 20).Select(x => $"Product {x}").ToList(); + + private List ProductModels = Enumerable.Range(1, 20).Select(x => new Product { ProductId = x, ProductName = "Product " + x }).ToList(); + + private List SelectedProducts { get; set; } + + public class Product + { + public int ProductId { get; set; } + public string ProductName { get; set; } + } +} + + +```` + +## Adding a Suffix Adornment + +To add a suffix, declare a `<*ComponentName*SuffixTemplate>` tag as a direct child of the `` tag. The `SuffixTemplate` is a `RenderFragment`, which allows you to declare any desired content as a prefix—a simple text, HTML elements, or components. + +>caption Adding a suffix adornment in UI for Blazor + +````CSHTML +
+
TextArea
+ + + + + + +
+ +
+
TextBox
+ + + + + + +
+ +
+
MaskedTextBox
+ + + + + + +
+ +
+
NumericTextBox
+ + + + + + +
+ +
+
AutoComplete
+ + + + + + +
+ +
+
ComboBox
+ + + + + + +
+ +
+
MultiColumnComboBox
+ + + + + + + + + + +
+ +
+
MultiSelect
+ + + + + + +
+ +@code { + private string TextValue { get; set; } + private string SelectedProduct { get; set; } + private int SelectedProductId { get; set; } + private int Height { get; set; } + + private List Products = Enumerable.Range(1, 20).Select(x => $"Product {x}").ToList(); + + private List ProductModels = Enumerable.Range(1, 20).Select(x => new Product { ProductId = x, ProductName = "Product " + x }).ToList(); + + private List SelectedProducts { get; set; } + + public class Product + { + public int ProductId { get; set; } + public string ProductName { get; set; } + } +} + + +```` + +## Using Separators + +By default, the prefix and suffix are visually divided from the input element of the components by a separator. You can control whether the prefix and suffix separator will be visible through the following parameters: + +@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout) + +| Parameter | Type and Default Value | Description | +| ----------- | ----------- | -------| +| `ShowPrefixSeparator` | `bool`
(`true`) | Specifies whether the prefix separator is rendered. If a prefix template is not declared, the separator will not be rendered, regardless of the parameter value. | +| `ShowSuffixSeparator` | `bool`
(`true`) | Specifies whether the suffix separator is rendered. If a prefix template is not declared, the separator will not be rendered, regardless of the parameter value | + +## TextArea Specifics + +In addition to the common configuration settings listed in this article, the TextArea exposes a couple of additional options that allow you to control the position of the adornments. + +@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout) + +| Parameter | Type and Default Value | Description | +| ----------- | ----------- | -------| +| `AdornmentsOrientation` | `TextAreaAdornmentsOrientation`
(`TextAreaAdornmentsOrientation.Vertical`) | Configures the positioning of the TextArea prefix and suffix templates. The possible values are `Horizontal` and `Vertical`. If the value is set to `Horizontal`, the templates will appear above (prefix) and below (suffix) the TextArea. If the value is set to `Vertical`, the templates will be displayed on the left (prefix) and on the right (suffix). By default, the templates are positioned vertically. | +| `AdornmentsFlow` | `TextAreaAdornmentsFlow`
(`TextAreaAdornmentsFlow.Horizontal`) | Configures the flow of the elements in the TextArea prefix and suffix templates, determining whether the elements will be ordered in a row or column. The possible values are `Horizontal` (in a row) and `Vertical` (in a column). By default, the elements (adornments) within the templates are positioned horizontally. | + +## FloatingLabel Specifics + +@[template](/_contentTemplates/common/inputs.md#floating-label-and-preffix) + +## DropDowns Specifics + +This section applies to the components that incorporate popup element: + +* [AutoComplete]({%slug autocomplete-overview%}) +* [ComboBox]({%slug components/combobox/overview%}) +* [MultiColumnComboBox]({%slug multicolumncombobox-overview%}) +* [MultiSelect]({%slug multiselect-overview%}) + +By design, `Alt` + `Down` key combination opens the popup element when the component is focused. If you have added another dropdown component as a prefix or suffix adornment, focusing that component and pressing `Alt` + `Down` keys will open both popup elements - the one that belongs to the main component and the other associated with the dropdown in the prefix/suffix template. + +To prevent that behavior, you may wrap the content of the prefix/suffix template and stop the `keydown` event propagation. + +>caption Stop the `keydown` event propagation + +````CSHTML + + +
+ + +
+ + +
+ + +
+ + + +@code { + private string SelectedTeam { get; set; } = "Team 1"; + + private string SelectedRole { get; set; } + + private List Roles { get; set; } = new List { + "Manager", "Developer", "QA", "Technical Writer", "Support Engineer", "Sales Agent", "Architect", "Designer" + }; + + private List Teams { get; set; } = new List { + "Team 1", "Team 2", "Team 3" + }; +} +```` + +## See also + +* [Live Demo: AutoComplete Adornments](https://demos.telerik.com/blazor-ui/autocomplete/adornments) +* [Live Demo: ComboBox Adornments](https://demos.telerik.com/blazor-ui/combobox/adornments) +* [Live Demo: MaskedTextBox Adornments](https://demos.telerik.com/blazor-ui/maskedtextBox/adornments) +* [Live Demo: MultiColumnComboBox Adornments](https://demos.telerik.com/blazor-ui/multicolumncombobox/adornments) +* [Live Demo: MultiSelect Adornments](https://demos.telerik.com/blazor-ui/multiselect/adornments) +* [Live Demo: NumericTextBox Adornments](https://demos.telerik.com/blazor-ui/numerictextBox/adornments) +* [Live Demo: TextArea Adornments](https://demos.telerik.com/blazor-ui/textarea/adornments) +* [Live Demo: TextBox Adornments](https://demos.telerik.com/blazor-ui/textbox/adornments) diff --git a/common-features/input-validation.md b/common-features/input-validation.md index fd7d202125..1ec0a9f53f 100644 --- a/common-features/input-validation.md +++ b/common-features/input-validation.md @@ -5,7 +5,7 @@ description: How to validate Blazor inputs. slug: common-features/input-validation tags: telerik,blazor,validation,data,annotation,form published: True -position: 2 +position: 3 --- # Input Validation diff --git a/common-features/loading-sign.md b/common-features/loading-sign.md index 02a52fddda..016aa205ee 100644 --- a/common-features/loading-sign.md +++ b/common-features/loading-sign.md @@ -5,7 +5,7 @@ description: Components that peform long running operations can show a loading i slug: common-features-loading-sign tags: telerik,blazor,loading,sign,busy,indicator,data published: True -position: 2 +position: 5 --- # Loading Sign diff --git a/components/autocomplete/overview.md b/components/autocomplete/overview.md index 91a8540549..d039c9a986 100644 --- a/components/autocomplete/overview.md +++ b/components/autocomplete/overview.md @@ -51,11 +51,13 @@ The Blazor AutoComplete @[template](/_contentTemplates/dropdowns/features.md#dat ## Filtering The Blazor AutoComplete @[template](/_contentTemplates/dropdowns/features.md#filtering) [Read more about the Blazor AutoComplete filter...]({%slug autocomplete-filter%}) - + ## Grouping The Blazor AutoComplete @[template](/_contentTemplates/dropdowns/features.md#grouping) [Read more about the Blazor AutoComplete grouping...]({%slug components/autocomplete/grouping%}) +@[template](/_contentTemplates/common/inputs.md#adornments) + ## Templates @[template](/_contentTemplates/dropdowns/features.md#templates) [Read more about the Blazor AutoComplete templates...]({%slug autocomplete-templates%}) diff --git a/components/combobox/overview.md b/components/combobox/overview.md index 0a36a27e21..71f541382f 100644 --- a/components/combobox/overview.md +++ b/components/combobox/overview.md @@ -57,6 +57,8 @@ The Blazor ComboBox @[template](/_contentTemplates/dropdowns/features.md#filteri The Blazor ComboBox @[template](/_contentTemplates/dropdowns/features.md#grouping) [Read more about the Blazor ComboBox grouping...]({% slug components/combobox/grouping %}). +@[template](/_contentTemplates/common/inputs.md#adornments) + ## Templates @[template](/_contentTemplates/dropdowns/features.md#templates) [Read more about the Blazor ComboBox templates...]({% slug components/combobox/templates %}). diff --git a/components/floatinglabel/overview.md b/components/floatinglabel/overview.md index dc8b3f6a62..35e697bed3 100644 --- a/components/floatinglabel/overview.md +++ b/components/floatinglabel/overview.md @@ -77,6 +77,9 @@ If a Telerik component has both a `Placeholder` and a floating label, the behavi * When the floating label is **over the component**, then the placeholder is **not rendered**. * When the floating label is **outside the component** and the focused component has no value, the placeholder **is visible**. +## Integration with Prefix Adornment + +@[template](/_contentTemplates/common/inputs.md#floating-label-and-preffix) ## FloatingLabel Parameters diff --git a/components/maskedtextbox/overview.md b/components/maskedtextbox/overview.md index 2bceb3fd3b..bf28607e51 100644 --- a/components/maskedtextbox/overview.md +++ b/components/maskedtextbox/overview.md @@ -35,6 +35,8 @@ The component value is: @MaskedValue } ```` +@[template](/_contentTemplates/common/inputs.md#adornments) + ## Validation You can validate the content of the `TelerikMaskedTextBox` using the Data Annotation attributes. [See the Input Validation article for an example on how to validate the content of the MaskedTextBox]({%slug common-features/input-validation%}#maskedtextbox). diff --git a/components/multicolumncombobox/overview.md b/components/multicolumncombobox/overview.md index 8ad3dad897..4ac36a5e89 100644 --- a/components/multicolumncombobox/overview.md +++ b/components/multicolumncombobox/overview.md @@ -65,39 +65,34 @@ The