# Element
## Description
BitElement renders whatever HTML tag the Element parameter names - a div by default, but just as easily an anchor, a button, an input, an SVG shape or a custom element - while still accepting the styling, direction and state parameters every other component of the library offers. Everything that is not a parameter is splatted onto that tag, so attributes and event handlers land on whichever element is rendered, and the class and style it builds are merged with the ones written as plain HTML attributes. The tag then decides the rest: a void element holds no content, a disabled element is disabled the way its own tag allows, and NoWrapper drops the tag altogether and leaves only the content behind. On top of that it reaches what Razor offers on a plain element and not on a component: the stopPropagation and preventDefault modifiers of the click and of any other event.
## Parameters
| Name | Type | Default Value | Description |
| :--- | :--- | :------------ | :---------- |
| ChildContent | `RenderFragment?` | null | The content of the element. A void element (such as input, img, br or hr) holds no content, so it is not rendered into one. |
| Element | `string?` | null | The custom html element used for the root node. Any tag name is accepted, including SVG and custom elements, and it is used exactly as written. A value that is not a name a tag can be made of - a letter followed by letters, digits and the "-", "_", "." and ":" that join them - falls back to the default, which is "div". |
| NoWrapper | `bool` | false | Renders only the content of the element, without the wrapping HTML tag, which makes the component a conditional wrapper. Everything that describes the element itself is then ignored, apart from a Collapsed Visibility, which drops the content as well. |
| PreventDefault | `bool` | false | Prevents the default browser action of the click event of the element, which is the @onclick:preventDefault directive Razor only accepts on a plain HTML element. |
| PreventDefaultEvents | `IEnumerable<string>?` | null | The names of the events whose default browser action is prevented on the element, with or without the "on" prefix. This is PreventDefault for every event other than the click, and naming the click here has the last word over that parameter. |
| StopPropagation | `bool` | false | Stops the click event of the element from bubbling up to its ancestors, which is the @onclick:stopPropagation directive Razor only accepts on a plain HTML element. |
| StopPropagationEvents | `IEnumerable<string>?` | null | The names of the events that are stopped from bubbling up from the element to its ancestors, with or without the "on" prefix. This is StopPropagation for every event other than the click, and naming the click here has the last word over that parameter. |
| 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 |
| :--- | :--- | :------------ | :---------- |
| FocusAsync | `ValueTask` | | Gives the browser focus to the rendered element, which has to be one the browser can focus: a tag that is focusable of itself, or any other tag carrying a TabIndex. The overload taking a preventScroll flag focuses it without the browser scrolling the document to bring it into view. Nothing is rendered while NoWrapper is set and nothing is captured before the first render, so there the call does nothing rather than fail. |
| 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
### 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. |
## Examples
\n**Basic**:
```razor
This is the default element (a div).
```
\n**Element**:
```razor
A heading (h4)
A paragraph (p) with a highlighted (mark) word in it.
A quotation (blockquote)
A code span (code)
A tag name carrying whitespace falls back to a div.
And so does one carrying a symbol no tag name is made of.
```
\n**SVG & custom elements**:
```razor
A custom element (demo-badge)
```
\n**Void elements**:
```razor
This content is not rendered, because a br holds none.
```
\n**Attributes & events**:
```razor
An anchor to bitplatform.dev
Clicked @counter times
You typed: @typed
```
```csharp
private int counter;
private string? typed;
```
\n**Event modifiers**:
```razor
An anchor that does not navigate (@prevented)
A disabled button
A disabled anchor
```
```csharp
private int counter;
```
\n**Visibility**:
```razor
Hidden keeps its space.
Collapsed takes its space with it.
Even unwrapped content is dropped while collapsed.
```
```csharp
private bool isVisible = true;
```
\n**No wrapper**:
```razor
The same content, highlighted or bare.
```
```csharp
private bool wrapped = true;
```
\n**Dynamic element**:
```razor
@element
```
```csharp
private string element = "div";
private List> elementsList =
[
new() { Text = "div", Value = "div" },
new() { Text = "a", Value = "a" },
new() { Text = "input", Value = "input" },
new() { Text = "button", Value = "button" },
new() { Text = "textarea", Value = "textarea" },
new() { Text = "progress", Value = "progress" }
];
```
\n**Element reference**:
```razor
A div, focusable because it has a TabIndex.
Focus the input
Focus the div without scrolling
```
```csharp
private BitElement? boxElement;
private BitElement? inputElement;
private async Task FocusTheInput()
{
if (inputElement is null) return;
await inputElement.FocusAsync();
}
private async Task FocusTheBox()
{
if (boxElement is null) return;
await boxElement.FocusAsync(preventScroll: true);
}
```
\n**Style & Class**:
```razor
Styled through the Style parameter
Classed through the Class parameter
Both a Class parameter and a splatted style
```
\n**RTL**:
```razor
این یک المنت راستچین است.
یک نقل قول راستچین.
```
The card was clicked @card times.
Stops propagation (@inner)
Bubbles up (@inner)
The card was double-clicked @doubled times.
Double-click keeps the card out of it, right-click opens no browser menu (@inner)
```
```csharp
private int card;
private int inner;
private int doubled;
private int prevented;
```
\n**Disabled**:
```razor