Utilities

Label

Bit.BlazorUI

BitLabel renders a native label element, so clicking it focuses the control it names and a screen reader announces that control by its text. It marks a field as required or optional, renders a group caption on any other tag, truncates or hides itself accessibly, and is restyled through its parameters, its public CSS variables or a BitParams cascade.

ForceAnimation (whole page)

Notes

A label names a control, it does not carry its state: the control still needs its own required (or aria-required), disabled and aria-invalid attributes. A native label names one control only, so a group caption belongs on another tag through Element - as does a BitLabel put in another component's LabelTemplate, which is a label already (Element='span').

Usage

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

Basic

A label element at the weight and size of the labels the inputs render of their own. Disabled only dims it: the label still names its control, so disable the control itself.

I'm a Label I'm a disabled Label

For & wrapping

For takes the id of the control, which may sit anywhere on the page. A control put inside the label is named without an id. Either way, clicking the caption focuses the control.

A Label for an input

A Label wrapping its own control

Required & optional

Required adds an asterisk hidden from screen readers - the control's own required attribute is what announces it. Optional adds a spoken "(optional)", for forms where the exceptions are the optional fields. RequiredText / OptionalText or the templates replace either (and a replaced required mark is spoken); set both and the required one wins.

A word instead of the asterisk(required) A custom required template A disabled Label dims its mark too I'm an optional Label(optional) Its own optional text- if you have one A custom optional templateoptional

Group captions

A label names one control only, so a group's caption uses Element to render another tag with the same look: one the group points at through aria-labelledby, or the legend of a fieldset. For is dropped off any tag but a label, and an invalid tag name falls back to label.

Favorite color

Red Green Blue

Delivery notes(optional) Leave with a neighbour Ring the doorbell

NoWrap & NoSelect

A label wraps and breaks long words. NoWrap keeps it on one line and truncates the caption, never its required or optional mark; a title gives pointer users the cut text back (screen readers read it all anyway). NoSelect stops a double click on the caption of a checkbox from selecting its text - try both.

A caption long enough to need more than one line at this width A caption long enough to need more than one line at this width Selectable caption Unselectable caption

Hiding

VisuallyHidden takes the label off the page but keeps it naming its control for screen readers; one wrapping its control reappears while that control has the focus (tab past the search box). Visibility hides the label from everyone, assistive technologies included.

Search the documentation

Shown only while its checkbox has the focus

Visible: [ Visible Label ]

Hidden: [ Hidden Label ]

Collapsed: [ ]

CSS variables

The public --bit-Label-* variables inherit, so one set on :root or a container restyles every label inside it, and one set in Style restyles that label. Color and Size win over the variables. The weight defaults to the theme's --bit-tpg-field-label-font-weight, which also sets the inputs' own labels.

Name (set on the container) Nickname (set on the container)(optional)

Set on one label

City (a BitLabel)

Country (a BitTextField's own label)

Cascading parameters

BitParams with a BitLabelParams sets defaults for every label under it; a label's own value wins (the last one opts out of Required). The content, For and the templates are not cascaded.

First name(required) Last name(required) Middle name(optional)

Color

A label takes its container's color until Color gives it a meaning of its own, such as an error beside a failed field. Accent colors use the role's readable text shade; the required mark keeps its own color.

Primary Secondary Tertiary Info Success Warning SevereWarning Error PrimaryForeground SecondaryForeground TertiaryForeground PrimaryBorder SecondaryBorder TertiaryBorder

Size

Size moves the caption along the type ramp. Unset means medium, the size the inputs' own labels use.

Small Medium Large

Style & Class

Style and Class land on the root; Styles and Classes reach its parts: Root, RequiredIndicator and OptionalIndicator.

I'm a Label with Style I'm a Label with Class I'm a Label with Styles I'm a Label with Classes (optional)

RTL

Dir set to BitDir.Rtl lays the label out right to left, with the indicator still after the caption.

من یک برچسب هستم من یک برچسب الزامی هستم من یک برچسب اختیاری هستم(اختیاری)

CSS variables

The public custom properties this component reads off its root, for what no parameter covers.

Every variable is read with a fallback and never declared by the component, so it inherits like any other custom property: set one on :root (or in a [bit-theme] block) to restyle every instance, on any ancestor to restyle the ones inside it, or on the Style of one instance to restyle that one alone. Leave a variable unset and the component falls back to the theme token beside it.

BitLabel CSS variables

Name	Default value	Description
--bit-Label-color	inherit	Color of the caption. The Color parameter wins over it.
--bit-Label-font-size	--bit-tpg-fs-sm	Size of the text. The Size parameter wins over it.
--bit-Label-font-weight	--bit-tpg-field-label-font-weight	Weight of the caption. The theme token sets it for every field caption at once.
--bit-Label-line-height	spacing(2.5) (20px)	Height of a line of the caption.
--bit-Label-padding	spacing(0.625) 0 (5px 0)	Room around the caption.
--bit-Label-indicator-gap	spacing(0.625) (5px)	Gap between the caption and its required or optional indicator.
--bit-Label-required-color	--bit-clr-req	Color of the required indicator.
--bit-Label-optional-color	--bit-clr-fg-sec	Color of the optional indicator.
--bit-Label-focus-color	--bit-clr-pri-focus	Color of the focus ring of a label given a TabIndex.

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: text or any markup. A control put inside it is named without For.
Classes	BitLabelClassStyles?	null	Custom CSS classes for the different parts of the label.
Color	BitColor?	null	The general color of the label. Inherits the color of its container while not set.
Element	string?	null	The html element of the root, for a group caption (div, legend, ...). Defaults to "label", which an invalid tag name falls back to.
For	string?	null	The id of the control the label names (the "for" attribute). Ignored when Element renders another tag.
NoSelect	bool	false	Prevents the text of the label from being selected, e.g. by a double click on the caption of a checkbox.
NoWrap	bool	false	Keeps the label on a single line and truncates its content with an ellipsis. The required or optional indicator is never cut off.
Optional	bool	false	Renders the optional indicator after the content. Ignored while Required is set.
OptionalTemplate	RenderFragment?	null	The custom template of the optional indicator. Takes precedence over OptionalText.
OptionalText	string?	null	The text of the optional indicator. The default is "(optional)".
Required	bool	false	Renders the required indicator after the content. The default asterisk is hidden from assistive technologies.
RequiredTemplate	RenderFragment?	null	The custom template of the required indicator, announced by screen readers. Takes precedence over RequiredText.
RequiredText	string?	null	The text of the required indicator, announced by screen readers. The default is "*".
Size	BitSize?	null	The size of the label. Unset means medium.
Styles	BitLabelClassStyles?	null	Custom CSS styles for the different parts of the label.
VisuallyHidden	bool	false	Hides the label from the page but not from assistive technologies, so it still names its control. It reappears while a control inside it has the focus.

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.
Disabled	bool	false	Gets or sets a value indicating whether the component is disabled and cannot respond to user interaction.
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.
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.

Open an issue

Start a discussion

Edit this page

View the component source

Edit the component