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.
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.
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.
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.
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
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.
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.
Visible: [ ]
Hidden: [ ]
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.
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.
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.
Size
Size moves the caption along the type ramp. Unset means medium, the size the inputs' own labels use.
Style & Class
Style and Class land on the root; Styles and Classes reach its parts: Root,
RequiredIndicator and OptionalIndicator.
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 it - and any instance nested inside it, which inherits the value too; a parameter changes one alone,
as does the real CSS property on the instance's Style / Styles when that property does not inherit (opacity: 1 keeps
one disabled instance undimmed without undimming a disabled one inside it), while an inherited one such as color or
font-family also reaches the nested instances that do not set it themselves. 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. While it is unset, the focus ring is the library's own --bit-shd-focus-ring, so replacing that token re-shapes it too. |
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. An attribute written on the component wins over an entry of the same name. |
| 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.