Skip to content
BlazorUI

Utilities

Label

Bit.BlazorUI

BitLabel renders a native label element, so the browser binds it to the control it names of itself: clicking the label focuses that control, and a screen reader announces the control by the label's text. The control is named either by For, which points at its id, or by putting it inside the label's own content. Required and Optional render the necessity of the field beside the caption - with the text of either indicator open to a string or to a template - and Element renders the caption as a plain tag for the groups of controls a single label may not name. Color, Size, NoWrap and the class and style parameters take care of how it looks, and VisuallyHidden keeps a caption for assistive technologies where the design has no room for one on the page.

Notes

A label names a control, it does not carry its state. The required asterisk is a decoration the component hides from assistive technologies, so the control itself still needs its own required (or aria-required) attribute for a screen reader to announce it as required; and IsEnabled only dims the caption, so it is the control that has to be disabled for a click on the caption to stop reaching it. A native label may also name a single control only: the caption of a group of controls belongs on another tag through Element, pointed at by the group's own aria-labelledby or rendered as the legend of a fieldset.

Usage

Every example is live. Open its code to see exactly what produced the component running underneath.

Basic

A label with nothing configured is a label element carrying the caption it is given, at the same weight and size as the labels the input components of the library render of their own. IsEnabled set to false dims it to the disabled foreground color of the theme. That is a look and not a state: a label is never itself disabled, so it still names its control and a click on it still reaches that control - disabling the control is what stops it from responding.

For

For is the for attribute of the label element: the value is the id of the control the label names, not its name, and that control may sit anywhere on the page. This is the explicit association of HTML, and it is what makes clicking the caption focus the field and a screen reader read the caption when the field takes focus. A control put inside the label's own content is associated implicitly instead, which is the one way to name a control that has no id.


Required

Required renders an indicator after the caption. The default one is an asterisk in the theme's required color, and it is hidden from assistive technologies: a star announced in the middle of a caption says nothing about the field, while the required attribute of the control itself is what makes it announced as required. RequiredText puts another mark or a word in the asterisk's place and RequiredTemplate puts any markup there - and an indicator written by the page is left announced, since a word put there deliberately is meant to be read.


Optional

Optional is the other half of the same decision, for the forms where most of the fields are required and it is the exceptions that are worth marking - marking every field of a form is noise whichever half is marked. The indicator is the word "(optional)" in a lighter color and a regular weight, and unlike the asterisk it is announced with the rest of the caption. OptionalText and OptionalTemplate replace it, which is what a form in another language needs. A label asked for both renders the required indicator, since a required field is not an optional one.


Element

A native label may only name a single form control, so the caption of a group of controls - a set of radio buttons, a pair of inputs making up a range - must not be one: it would name only the first control in the group. Element renders the caption as any other tag while keeping the same look, so the group can point at it through its own aria-labelledby - or as the legend of a fieldset, which is the same association written in plain HTML. The For parameter is dropped along with the label element, since the for attribute belongs to that element alone. A tag name that is not one a tag can have falls back to label.
Favorite color

Delivery notes(optional)

Wrapping

A label wraps by default and breaks a word too long for its line rather than overflowing it. NoWrap keeps it on one line and truncates what does not fit with an ellipsis. Truncation needs a width to overflow: a label is a block element whichever tag Element renders, so it takes the width of its container, and only a label given a display of its own needs a width of its own.

NoSelect

A click on a label is forwarded to the control it names, so a double click on one - whose second click lands on the label rather than on the control - selects the caption's text instead of doing anything to the control. NoSelect turns that selection off, for the labels over a checkbox or a toggle where it is only ever an accident. Try double clicking both captions below.

Visually hidden

VisuallyHidden clips the label out of the page while leaving it in the accessibility tree, so the control it names is still announced by its caption. That is what separates it from Visibility below, which takes the label away from assistive technologies along with the page. A visible caption is what most users need, so this belongs to the places where the surrounding design already says what the control is.

Visibility

Visibility decides whether the label is rendered, invisible but still taking its space, or out of the layout altogether. A hidden or a collapsed label is gone from the accessibility tree as well, so it no longer names its control - VisuallyHidden above is the one that keeps naming it.
Visible: [ ]

Hidden: [ ]

Collapsed: [ ]

Color

A label inherits the color of its container while Color is not set, which is what keeps it in step with the text around it. Setting it gives the caption a meaning of its own - an error color beside a field that failed its validation, a secondary foreground for a caption that should sit back from the content it names. The required indicator keeps the theme's required color whichever color the caption takes.

Size

Size moves the caption along the type ramp of the theme. The unset default is the medium size, which is the one that matches the labels the input components render of their own, so a standalone label sits next to them without being resized.

Style & Class

Style and Class land on the root element of the label, and Styles and Classes reach its parts one by one: the root, the required indicator and the optional indicator. That is how the necessity mark is restyled - a color, a weight, a position - without a selector reaching into the library's own class names.
Component's Style & Class:





Styles & Classes:


RTL

Setting Dir to BitDir.Rtl lays the label out right to left. The gap between the caption and its necessity indicator is a logical one, so the mark stays after the caption - on its left in this direction - rather than jumping to the other side of it.


API

Every parameter, public member, sub-class and enum this component exposes.

BitLabel parameters

Name Type Default value Description
ChildContent RenderFragment? null The content of the label, which can be a text or any custom markup. A form control put inside it is named by the label without needing the For parameter.
Classes BitLabelClassStyles? null Custom CSS classes for the different parts of the label.
Color BitColor? null The general color of the label. The label inherits the color of its container while this is not set.
Element string? null The custom html element used for the root node. The default is "label", and a name that is not one a tag can have falls back to it.
For string? null The id of the form control this label is bound to, rendered as the "for" attribute of the label element. It is ignored while the Element parameter renders another tag.
NoSelect bool false Prevents the text of the label from being selected, which is what a double click on a label does instead of reaching the control it names.
NoWrap bool false Keeps the label on a single line and truncates the overflow with an ellipsis.
Optional bool false Whether the associated field is optional, which renders an indicator after the content of the label. It is ignored while Required is set.
OptionalTemplate RenderFragment? null The custom template of the optional indicator of the label. Takes precedence over OptionalText.
OptionalText string? null The text of the optional indicator of the label. The default is "(optional)".
Required bool false Whether the associated field is required, which renders an indicator after the content of the label. The default asterisk is hidden from assistive technologies.
RequiredTemplate RenderFragment? null The custom template of the required indicator of the label. Takes precedence over RequiredText.
RequiredText string? null The text of the required indicator of the label. The default is "*".
Size BitSize? null The size of the label. The default is the medium size.
Styles BitLabelClassStyles? null Custom CSS styles for the different parts of the label.
VisuallyHidden bool false Removes the label from the page while keeping it available to assistive technologies, so it still names its control.

BitComponentBase parameters

Name Type Default value Description
AriaLabel string? null Gets or sets the accessible label for the component, used by assistive technologies.
Class string? null Gets or sets the CSS class name(s) to apply to the rendered element.
Dir BitDir? null Gets or sets the text directionality for the component's content.
ForceAnimation bool false Gets or sets a value indicating whether the component's animations play at their full duration even when reduced motion is requested.
HtmlAttributes Dictionary<string, object> new Dictionary<string, object>() Captures additional HTML attributes to be applied to the rendered element, in addition to the component's parameters.
Id string? null Gets or sets the unique identifier for the component's root element.
IsEnabled bool true Gets or sets a value indicating whether the component is enabled and can respond to user interaction.
Style string? null Gets or sets the CSS style string to apply to the rendered element.
TabIndex string? null Gets or sets the tab order index for the component when navigating with the keyboard.
Visibility BitVisibility BitVisibility.Visible Gets or sets the visibility state (visible, hidden, or collapsed) of the component.

BitComponentBase public members

Name Type Default value Description
UniqueId Guid Guid.NewGuid() Gets the readonly unique identifier for the component's root element, assigned when the component instance is constructed.
RootElement ElementReference Gets the reference to the root HTML element associated with this component.

BitLabelClassStyles properties

The custom CSS classes/styles for the different parts of the label.

Name Type Default value Description
Root string? null Custom CSS classes/styles for the root element of the label.
RequiredIndicator string? null Custom CSS classes/styles for the required indicator of the label, which only exists while Required is set.
OptionalIndicator string? null Custom CSS classes/styles for the optional indicator of the label, which only exists while Optional is set and Required is not.

BitColor enum

Name Value Description
Primary 0 Primary general color.
Secondary 1 Secondary general color.
Tertiary 2 Tertiary general color.
Info 3 Info general color.
Success 4 Success general color.
Warning 5 Warning general color.
SevereWarning 6 SevereWarning general color.
Error 7 Error general color.
PrimaryBackground 8 Primary background color.
SecondaryBackground 9 Secondary background color.
TertiaryBackground 10 Tertiary background color.
PrimaryForeground 11 Primary foreground color.
SecondaryForeground 12 Secondary foreground color.
TertiaryForeground 13 Tertiary foreground color.
PrimaryBorder 14 Primary border color.
SecondaryBorder 15 Secondary border color.
TertiaryBorder 16 Tertiary border color.

BitSize enum

Name Value Description
Small 0 The small size.
Medium 1 The medium size.
Large 2 The large size.

BitVisibility enum

Name Value Description
Visible 0 The content of the component is visible.
Hidden 1 The content of the component is hidden, but the space it takes on the page remains (visibility:hidden).
Collapsed 2 The component is hidden (display:none).

BitDir enum

Name Value Description
Ltr 0 Ltr (left to right) is to be used for languages that are written from the left to the right (like English).
Rtl 1 Rtl (right to left) is to be used for languages that are written from the right to the left (like Arabic).
Auto 2 Auto lets the user agent decide. It uses a basic algorithm as it parses the characters inside the element until it finds a character with a strong directionality, then applies that directionality to the whole element.

Feedback

Found a mistake, a gap, or something that could be clearer? Every page and every component is one click from its source.