Skip to content
# Text **Also known as:** Typography ## Description BitText draws text at one of the theme's typography steps and keeps the look apart from the semantics: Typography picks the look, Element the tag and AriaLevel the announced heading level. Weight, emphasis, colors, gradients, wrapping, truncation and line clamping compose with any variant. ## Parameters | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | Align | `BitTextAlign?` | null | Sets the horizontal alignment of the text content. Start and End follow the direction of the text, while Left and Right do not. | | AriaLevel | `int?` | null | Sets the level of the heading the text is announced as, without changing the rendered tag. On a tag that is not already a heading a heading role is written beside it. | | Block | `bool` | false | Renders the text as a block level element, which is what the inline variants need before they have a width to align inside or to truncate. | | BreakWord | `bool` | false | Breaks a word that is too long for its line rather than letting it overflow, leaving the words that do fit alone. | | ChildContent | `RenderFragment?` | null | The content of the text. It is not rendered where Element names a void element. | | Color | `BitColor?` | null | The general color of the text. | | Element | `string?` | null | The custom html element used for the root node. A value that is not a name a tag can have falls back to the tag of the typography variant. | | ForceBreak | `bool` | false | Breaks the text wherever the line runs out, even in the middle of a word. | | Foreground | `BitColorKind?` | null | The kind of the foreground color of the text. | | Gradient | `string?` | null | Paints the glyphs of the text with a CSS gradient instead of with a flat color. The value is written as the background-image of the element and clipped to the text, and the fill is taken away by itself. | | Gutter | `bool` | false | Adds a bottom margin in em, so it follows the size of the variant. An inline variant needs Block for it to show. | | Hyphenate | `bool` | false | Hyphenates the words that are broken across two lines, which needs a Lang the browser carries a dictionary for. | | Italic | `bool` | false | Renders the text in italics. | | Lang | `string?` | null | The language of the text, written as the lang attribute of the rendered element. | | LineClamp | `int?` | null | Truncates the text after the given number of lines with an ellipsis. A value below one leaves the text alone. | | Monospace | `bool` | false | Renders the text in the theme's monospaced family, so that every character is drawn at the same width and a column of them lines up. | | NoSelect | `bool` | false | Prevents the text from being selected. | | NoWrap | `bool` | false | Keeps the text on a single line and ends it with an ellipsis. Needs a box with a width, which Block gives an inline variant. | | Numeric | `bool` | false | Renders the digits of the text at a single width, so that they line up across the lines. | | PreserveWhitespace | `bool` | false | Renders the line breaks and the runs of spaces of the content as they were written, while the lines still too wide for the box go on wrapping. NoWrap has the last word over it. | | Strikethrough | `bool` | false | Draws a line through the text. It combines with Underline. | | Transform | `BitTextTransform?` | null | The capitalization of the text. The transform is visual only, so the characters in the document are the ones that were written. | | Trim | `BitTextTrim?` | null | Trims the half-leading off the top, the bottom or both edges of the box the text draws in, so that the gap around it is the one that was written. | | Typography | `BitTypography?` | null | The typography variant: the size, weight, line height and tracking, and the tag rendered unless Element is set. Only the six heading variants render a heading tag. Defaults to Subtitle1. | | Underline | `bool` | false | Underlines the text. It combines with Strikethrough. | | VisuallyHidden | `bool` | false | Removes the text from the page while keeping it available to assistive technologies. It is drawn again while it holds the focus, so a skip link stays visible when tabbed to. | | Weight | `BitFontWeight?` | null | The font weight of the text. Left unset, the weight is the one the typography variant carries. | | Wrap | `BitTextWrap?` | null | How the lines of the text are broken. NoWrap and LineClamp have the last word over it. | | 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. | ## 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. | ### BitColorKind Enum | Name | Value | Description | | :--- | :--- | :---------- | | Primary | 0 | The primary color kind. | | Secondary | 1 | The secondary color kind. | | Tertiary | 2 | The tertiary color kind. | | Transparent | 3 | The transparent color kind. | ### BitFontWeight Enum | Name | Value | Description | | :--- | :--- | :---------- | | Light | 0 | The lightest step of the weight scale. | | Regular | 1 | The weight of body copy, and the default of nearly every typography variant. | | Medium | 2 | The step between the body copy and the titles. | | Semibold | 3 | The weight of the titles and of the labels of the interactive controls. | | Bold | 4 | The heaviest step of the weight scale. | ### BitTextAlign Enum | Name | Value | Description | | :--- | :--- | :---------- | | Start | 0 | Aligns to the leading edge of the text, whichever direction it runs in. | | End | 1 | Aligns to the trailing edge of the text, whichever direction it runs in. | | Left | 2 | Aligns to the left edge, whichever direction the text runs in. | | Right | 3 | Aligns to the right edge, whichever direction the text runs in. | | Center | 4 | Centers the lines inside the box. | | Justify | 5 | Spaces the words of every line but the last so that both edges line up. | | JustifyAll | 6 | Justifies the last line as well. No browser engine implements it yet. | | MatchParent | 7 | Inherits the alignment, resolving a start or an end against the direction of the parent. | | Inherit | 8 | Takes the alignment of the parent. | | Initial | 9 | Takes the initial value of the property. | | Revert | 10 | Reverts to the value the user agent or the user stylesheet sets. | | RevertLayer | 11 | Reverts to the value of the previous cascade layer. | | Unset | 12 | Inherits the alignment, or takes the initial value where it is not inherited. | ### BitTextTransform Enum | Name | Value | Description | | :--- | :--- | :---------- | | None | 0 | The text is rendered with the capitalization it was written in. | | Uppercase | 1 | Every character is rendered in upper case. | | Lowercase | 2 | Every character is rendered in lower case. | | Capitalize | 3 | The first character of every word is rendered in upper case. | ### BitTextTrim Enum | Name | Value | Description | | :--- | :--- | :---------- | | None | 0 | Neither half-leading is trimmed, which is what a line box does of its own. | | Start | 1 | The half-leading above the first line is trimmed, so that the top of the box is the cap height of the text. | | End | 2 | The half-leading below the last line is trimmed, so that the bottom of the box is the alphabetic baseline. | | Both | 3 | Both half-leadings are trimmed, so that the box is exactly as tall as the glyphs it draws. | ### BitTextWrap Enum | Name | Value | Description | | :--- | :--- | :---------- | | Wrap | 0 | The text is broken into lines the usual way. | | NoWrap | 1 | The text is not broken into lines at all and overflows its container instead. | | Balance | 2 | The lines are balanced so that they come out of a similar length. Engines only balance a short block. | | Pretty | 3 | The break points avoid leaving a short last line. This is the one for body copy. | | Stable | 4 | The lines already laid out keep their break points while the text after them is edited. | ### BitTypography Enum | Name | Value | Description | | :--- | :--- | :---------- | | H1 | 0 | Renders an h1. | | H2 | 1 | Renders an h2. | | H3 | 2 | Renders an h3. | | H4 | 3 | Renders an h4. | | H5 | 4 | Renders an h5. | | H6 | 5 | Renders an h6. | | Subtitle1 | 6 | Renders a div - not a heading. The default variant. | | Subtitle2 | 7 | Renders a div - not a heading. | | Body1 | 8 | Renders a p. | | Body2 | 9 | Renders a p. | | Button | 10 | Renders a span. | | Caption1 | 11 | Renders a span. | | Caption2 | 12 | Renders a span. | | Overline | 13 | Renders a span. | | Inherit | 14 | Renders a p, taking every typographic declaration from the element around it. | ### 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. | ## CSS Variables Public CSS custom properties read off the component's root. Set one on `:root` to restyle every instance, on any ancestor to restyle the ones inside it, or on the `Style` of one instance to restyle it and every instance nested inside it, which inherits the value too - a parameter changes one alone, as does the real CSS property on its `Style` / `Styles` when that property does not inherit (`opacity`); an inherited one (`color`, `font-family`) reaches the nested instances that do not set it themselves. | Name | Default Value | Description | | :--- | :------------ | :---------- | | `--bit-Text-color` | currentcolor (the color around the text) | Text color when neither Color nor Foreground is set. | | `--bit-Text-font-family` | --bit-tpg-font-family | Font family of every variant but Inherit, which keeps the family around it. | | `--bit-Text-heading-font-family` | --bit-Text-font-family | Font family of the H1 to H6 variants, for a display face beside the text face. | | `--bit-Text-monospace-font-family` | --bit-tpg-font-family-mono | Font family of a Monospace text. | | `--bit-Text-gutter` | --bit-tpg-gutter-size | Bottom margin of a Gutter text. | | `--bit-Text-decoration-color` | currentcolor | Color of the Underline and Strikethrough lines. | | `--bit-Text-decoration-thickness` | auto | Thickness of the Underline and Strikethrough lines. | | `--bit-Text-underline-offset` | auto | Distance between the baseline and the Underline line. | | `--bit-Text-disabled-opacity` | --bit-opa-dis | Opacity of a text whose Disabled is true. The variable inherits, so a value set on a text also becomes the disabled opacity of every disabled text nested in it. To change one text alone, set opacity on its Style instead: the opacity property is not inherited, so a nested disabled text keeps its own disabled opacity, though like any opacity it still fades everything rendered inside the text along with it. | ## Examples \n**Basic**: ```razor Default (Subtitle1) H1. Heading H2. Heading H3. Heading H4. Heading H5. Heading H6. Heading Subtitle1. Once upon a time Subtitle2. Once upon a time Body1. Once upon a time, stories wove connections between people, a symphony of voices crafting shared dreams. Body2. Once upon a time, stories wove connections between people, a symphony of voices crafting shared dreams. Button. Click me Caption1. Hello world! Caption2. Hello world! Overline. This is overline text
Inherit. Takes the size, the weight and the family of the element around it.
``` \n**Element**: ```razor An h2 drawn at the size of an h4 An h4 look with no heading semantics (span) Strongly emphasized body text A quotation, in a blockquote var text = new BitText(); An invalid tag name falls back to the variant's tag (p) A void element holds no content, so this is not rendered ``` \n**Weight & emphasis**: ```razor Light weight Regular weight Medium weight Semibold weight Bold weight Italic Underline Strikethrough Underline and strikethrough Uppercase transform capitalize transform None, undoing the overline's uppercase ``` \n**Numbers & monospace**: ```razor
Default 1,111.11 8,888.88
Numeric 1,111.11 8,888.88
Monospace 1,111.11 8,888.88
var text = new BitText { Monospace = true }; ``` \n**Truncation**: ```razor
NoWrap Once upon a time, stories wove connections between people, a symphony of voices crafting shared dreams.
NoWrap + Block on an inline caption Once upon a time, stories wove connections between people, a symphony of voices.
LineClamp="2", with a title Once upon a time, stories wove connections between people, a symphony of voices crafting shared dreams that outlasted every night they were told in.
``` \n**Wrapping**: ```razor
BreakWord A path: /a/very/long/path/segment/that/never/breaks/on/its/own/anywhere.txt
ForceBreak 1234567890123456789012345678901234567890123456789012345678901234567890
Wrap="Balance" A heading whose lines are balanced against each other
Hyphenate An incomprehensibly complicated internationalization responsibility.
PreserveWhitespace @(@"Dear reader, Blank lines and indents survive, and a line this long still wraps.")
``` \n**Align**: ```razor
Start Center End Justify. Once upon a time, stories wove connections between people, a symphony of voices crafting shared dreams.
``` \n**Gutter & trim**: ```razor
A heading with a gutter A paragraph with a smaller gutter A paragraph with none
None
Start
End
Both
``` \n**Foreground & gradient**: ```razor Primary foreground Secondary foreground Tertiary foreground A gradient headline A radial gradient Body text fading out into nothing ``` \n**Accessibility**: ```razor A div announced as a level 3 heading An h2 announced as a level 4 heading Read out by a screen reader, drawn nowhere. Skip to the next example Bonjour tout le monde This text cannot be selected ``` \n**Visibility & disabled**: ```razor
Visible: [Visible text]
Hidden: [Hidden text]
Collapsed: [Collapsed text]
Disabled text Disabled text, keeping its gradient ``` \n**Cascading parameters**: ```razor Takes the variant, the weight and the transform from the cascade So does this one Its own transform, the cascaded variant and weight Outside the cascade ``` ```csharp private readonly BitTextParams[] textParams = [ new() { Typography = BitTypography.Body1, Weight = BitFontWeight.Semibold, Transform = BitTextTransform.Uppercase, } ]; ``` \n**Color**: ```razor Primary Secondary Tertiary Info Success Warning SevereWarning Error
PrimaryBackground SecondaryBackground TertiaryBackground
PrimaryForeground SecondaryForeground TertiaryForeground PrimaryBorder SecondaryBorder TertiaryBorder ``` \n**Style & Class**: ```razor Styled through Style Classed through Class Splatted class and style, kept beside the alignment
A heading in a family of its own Color from --bit-Text-color Underline restyled through the decoration variables Monospace in another family An explicit Color still wins
``` \n**RTL**: ```razor این یک عنوان راست‌چین است این متن از لبه‌ی آغازین چیده شده است. این متن از لبه‌ی پایانی چیده شده است. ```