# Label
## Description
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.
## 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. |
| 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. |
## 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. |
## Enums
### 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. |
## Sub Classes
### 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. |
## Examples
\n**Basic**:
```razor
I'm a Label
I'm a disabled Label
```
\n**For**:
```razor
A Label for an input
A Label wrapping its own control
```
\n**Required**:
```razor
I'm a required Label
A required Label with a word instead of the asterisk
A required Label with a custom template
```
\n**Optional**:
```razor
I'm an optional Label
An optional Label with its own text
An optional Label with a custom template
```
\n**Element**:
```razor
Favorite color
```
\n**Wrapping**:
```razor
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
```
\n**NoSelect**:
```razor
Selectable caption
Unselectable caption
```
\n**Visually hidden**:
```razor
Search the documentation
```
\n**Visibility**:
```razor
Visible: [ Visible Label ]
Hidden: [ Hidden Label ]
Collapsed: [ Collapsed Label ]
```
\n**Color**:
```razor
Primary
Secondary
Tertiary
Info
Success
Warning
SevereWarning
Error
PrimaryForeground
SecondaryForeground
TertiaryForeground
PrimaryBorder
SecondaryBorder
TertiaryBorder
```
\n**Size**:
```razor
Small
Medium
Large
```
\n**Style & Class**:
```razor
I'm a Label with Style
I'm a Label with Class
I'm a Label with Styles
I'm a Label with Classes
```
\n**RTL**:
```razor
من یک برچسب هستم
من یک برچسب الزامی هستم
من یک برچسب اختیاری هستم
```