Utilities
Text
Bit.BlazorUI
BitText draws a run of text at one of the theme's named typography steps, so its size, weight, line height and tracking all come from the theme and every preset re-skins them at once. The look and the semantics stay separate decisions: the variant chooses how the text is drawn, Element the tag it is drawn in, and AriaLevel the heading level it is announced at. Everything else composes with any variant - the weight, the case, the italic, the underline and the strikethrough, the tabular figures, the alignment, the flat colors and the gradients, the trim of the box the text draws in, and the whole of the wrapping, from a single truncated line to a clamp of a given number of lines.
Usage
Every example is live. Open its code to see exactly what produced the component running underneath.
Basic
Typography picks the step of the theme's ramp the text is drawn at, and every one of them carries its
own size, weight, line height and tracking. It also decides the tag the text is rendered in unless
Element overrides it: the six heading variants render their own heading tag, the two subtitles an
h6, the two body variants a p, and the button, the two captions and the overline a
span. Left unset the variant is Subtitle1.
This is 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.
Element
Element names the tag to render, which is what keeps the semantics of the text apart from its looks:
an
h2 drawn at the size of an h4 keeps the outline a screen reader navigates
intact, while picking the smaller heading for its size alone would break it. It is also how the text reaches
the tags that mean something of their own and that no variant maps to - a strong, an
em, a blockquote, a label, a code. A value that is not a
name a tag can have falls back to the tag of the variant rather than reaching the markup, and a void element
such as hr is rendered without the content it cannot hold.
An h2 drawn at the size of an h4
An h4 look with no heading semantics at all (span) Strongly emphasized body textA quotation, in a blockquote
var text = new BitText();
A tag name carrying whitespace falls back to the tag of the variant (p).
Weight & emphasis
Weight moves the text along the theme's weight scale, so a preset that draws its semibold somewhere
else moves with it; left unset the weight is the one the variant carries. Italic, Underline and
Strikethrough are decorations that compose with any variant and with each other - asked for together
the last two draw a single underlined and struck through line. Transform changes the case the text is
drawn in without touching the characters in the document, so a copy and a screen reader both still get the
original text.
Light weight
Regular weight
Medium weight
Semibold weight
Bold weight
Italic text
Underlined text
Struck through text
Both underlined and struck through
Uppercase transform
Lowercase Transform
capitalize transform
None, undoing the uppercase of the overline variantNumbers & monospace
In an ordinary font a
Monospace is the wider answer, for the text that is not prose at all: every character is drawn at the same width, so a fragment of code, an identifier, a hash or a stack trace lines up down the page and none of its characters is mistaken for another. The family comes from the theme like every other typographic decision. It is a look and not a meaning, so where the text is code or a key the reader is meant to press, a
1 is narrower than an 8, so a column of figures comes out
ragged and a number that counts up visibly shifts under the eye. Numeric asks the font for its tabular
figures, which all share one width, and its lining figures, which all sit on the baseline; the letters beside
them stay proportional. A font that carries neither is left as it is.Monospace is the wider answer, for the text that is not prose at all: every character is drawn at the same width, so a fragment of code, an identifier, a hash or a stack trace lines up down the page and none of its characters is mistaken for another. The family comes from the theme like every other typographic decision. It is a look and not a meaning, so where the text is code or a key the reader is meant to press, a
code, a samp or a kbd through Element is what says so.
Proportional (default)
1,111.11
8,888.88
1,234.56
Numeric
1,111.11
8,888.88
1,234.56
Monospace
1,111.11
8,888.88
1,234.56
var text = new BitText { Monospace = true };
sha256:3f7a91c0b2ed48d5Wrapping
NoWrap keeps the text on a single line and cuts what does not fit with an ellipsis; it needs a box
with a width of its own to overflow, which is what Block gives to a variant that is left inline, such as a
caption. BreakWord breaks only a word that has no other way to fit - a URL, a hash, a path - and leaves
ordinary prose breaking between its words, while ForceBreak breaks wherever the line runs out.
Wrap chooses how the remaining lines are broken:
Inside a flex or a grid item, a truncation appears to do nothing: such an item is never allowed to become narrower than its longest word, so the text never overflows in the first place. BreakWord on the text or a
Balance evens out the lines of a short
heading, Pretty avoids leaving a short last line under body copy, and Stable keeps
the lines already laid out from re-flowing while the text is edited. Hyphenate hyphenates the words
broken across two lines, which needs a Lang the browser has a dictionary for.
PreserveWhitespace keeps the line breaks and the runs of spaces the content was written with, which
HTML would otherwise collapse into a single space - a message a person typed, an address, a stack trace -
while the lines still too wide for the box go on wrapping.Inside a flex or a grid item, a truncation appears to do nothing: such an item is never allowed to become narrower than its longest word, so the text never overflows in the first place. BreakWord on the text or a
min-width: 0 on the item is what lets it shrink and the ellipsis appear.
Normal wrap (default)
Once upon a time, stories wove connections between people, a symphony of voices crafting shared dreams.
NoWrap
Once upon a time, stories wove connections between people, a symphony of voices crafting shared dreams.
NoWrap on a caption, which is inline and needs Block for a width to overflow
Once upon a time, stories wove connections between people, a symphony of voices.
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
Wrap: Pretty
Once upon a time, stories wove connections between people, a symphony of voices crafting shared dreams.
Hyphenate, with a Lang the browser has a dictionary for
An incomprehensibly complicated internationalization responsibility.
PreserveWhitespace
Dear reader, Two blank lines and an indent survive, and a line this long is still wrapped.
Line clamp
LineClamp is the multi-line truncation: the text wraps normally up to the given line and everything
after it is clipped away, with the last visible line ending in an ellipsis. Nothing is taken out of the
document, so the whole text is still copied, found by a find-in-page and read out by a screen reader. A
bottom padding on a clamped element would show slivers of the lines underneath it, so that padding belongs on
a wrapper around the text, and a word wider than the box still overflows sideways unless BreakWord is
set beside it. A value below one leaves the text alone. Nothing tells a sighted reader that a truncation has
happened, so a clamped text is worth giving a plain
title attribute - it is not a parameter, so
it is splatted onto the rendered element like any other - or a tooltip beside it.
LineClamp="1"
Once upon a time, stories wove connections between people, a symphony of voices crafting shared dreams that outlasted every one of the nights they were told in.
LineClamp="2"
Once upon a time, stories wove connections between people, a symphony of voices crafting shared dreams that outlasted every one of the nights they were told in.
LineClamp="3"
Once upon a time, stories wove connections between people, a symphony of voices crafting shared dreams that outlasted every one of the nights they were told in.
Align
Align sets the horizontal alignment of the lines inside the box the text occupies.
Start and End are the logical values and follow the direction of the text, so the
same markup reads from the leading edge of a left-to-right and of a right-to-left page alike, which
Left and Right deliberately do not. Justify spaces the words of every
line but the last so both edges line up - WCAG advises against it for a block of text, since the uneven word
spacing is harder to read for people with dyslexia and other cognitive concerns.
Start
Center
End
Justify. Once upon a time, stories wove connections between people, a symphony of voices crafting shared dreams.
Gutter
Gutter puts a bottom margin under the text. It is set in
em, so it follows the size of
the variant: the gap under a heading comes out larger than the one under a caption without either of them
naming a length.
A heading with a gutter
A paragraph with a gutter, whose margin is smaller because the variant is.
A paragraph with none.
Trim
A line box is taller than the glyphs it draws: whatever the line height adds over the font's own metrics is
split into a half-leading above the ascenders and one below the descenders, and neither of them is part of
anything a design measures from. So a heading given a margin of its own is spaced by that margin plus two
leadings nobody asked for, and the larger the variant the more of it there is. Trim takes one or both
of them off -
Start makes the top of the box the cap height, End makes the bottom
of it the alphabetic baseline, and Both leaves the box exactly as tall as the glyphs - so that
the gap above and below a run of text is the gap that was written. A browser that has not implemented the
underlying property lays the text out with both leadings intact, exactly as it would have anyway.
None (default)
Handgloves
Trim: Start
Handgloves
Trim: End
Handgloves
Trim: Both
Handgloves
Accessibility
AriaLevel is the third axis beside the look and the tag: it sets the heading level the text is
announced at without moving either of them, for a component reused at several depths or a caption that has to
stay a
div. On a tag that is not already a heading it writes a heading role beside the level,
since a level on its own names nothing. VisuallyHidden takes the text off the page while leaving it in
the accessibility tree, which neither a hidden nor a collapsed Visibility does, and NoSelect
keeps a run of chrome text from being selected by a stray double click - content itself stays selectable, so
that a reader can still copy it into a translator or a note.
A div announced as a level 3 heading
An h2 announced as a level 4 heading
Read out by a screen reader, and drawn nowhere.
Try to select this text - it will not be selected.
Visibility & disabled
Visibility decides whether the text is drawn, invisible but still taking its space, or out of the
layout altogether. A hidden or a collapsed text is gone from the accessibility tree as well and is announced
nowhere - VisuallyHidden above is the one that keeps it there. IsEnabled dims the text rather
than recoloring it, so it keeps whichever color role it was given and only reads as unavailable; a run of
text is not interactive to begin with, so there is nothing else about it to turn off.
Visible: [
Visible text
]Hidden: [
Hidden text
]Collapsed: [
Collapsed text
]A disabled run of text
A disabled run of text, keeping its error color
Foreground
Foreground paints the text with one of the theme's three neutral foreground colors - the primary one
for body copy, the secondary and the tertiary for the text that should recede beside it.
Transparent
leaves the glyphs unpainted so that whatever the box behind them paints shows through; in a forced-colors
palette, where that painting is removed, the text is given the system color back so that it never comes out
invisible. Where the painting is a gradient of the text's own, Gradient below is the shorter way to
the same result, and it takes the fill away by itself.
Primary foreground
Secondary foreground
Tertiary foreground
Transparent foreground
Gradient
Gradient paints the glyphs themselves rather than the box around them: the value is written as the
background-image of the element and what it paints is then clipped to the text, so anything a
background-image accepts works here - a linear-gradient, a
radial-gradient, a conic-gradient, or several of them layered over each other.
The glyphs have to be left unpainted for that to show through, so this takes the fill away by itself and
there is nothing to set beside it. The clip is a paint time effect, so a copy, a find-in-page and a screen
reader all still get the text; in a forced-colors palette, where every gradient is removed, the text is
given the system color back. A gradient is not a contrast ratio, so a headline that has to be readable is
worth checking against its background at both ends of it.
A gradient headline
Three stops, on a diagonal
A radial gradient, and a weight of its own
A run of body text fading out into nothing
Cascading parameters
BitParams carries a BitTextParams down to every text under it, so a section of a page sets a
variant, a color or a wrapping once instead of at every run of text in it. What it carries is a default and
not an override: a text that sets a parameter for itself keeps its own value, and only what it left unset is
filled in from the cascade - which is what lets one text step out of the section it is in without the
section having to know about it. Every parameter of the component is on the params object, and each of them
is filled in on its own, so a text can take the variant from the cascade and the weight from its own markup.
Takes the variant, the color and the transform from the cascade
So does this one, without repeating any of it
Its own color and weight, the cascaded variant
Outside the cascade, and back to the defaults
Color
Color paints the text with one of the general color roles of the library: the three accents, the four
states, and the neutral background, foreground and border families for the text that has to sit against one
of those surfaces. Color alone is never the only thing that carries a meaning, so a success or an error is
worth pairing with a word or an icon that says the same thing.
Primary color
Secondary color
Tertiary color
Info color
Success color
Warning color
SevereWarning color
Error color
PrimaryBackground color
SecondaryBackground color
TertiaryBackground color
PrimaryForeground color
SecondaryForeground color
TertiaryForeground color
PrimaryBorder color
SecondaryBorder color
TertiaryBorder color
Style & Class
Style and Class apply to the rendered element like they do on every other component of the
library, and they are added to the class list and the style the component builds of its own rather than
replacing them. The same holds of a
class or a style arriving through
@attributes: it is merged with what the component builds, so the variant, the colors and the
alignment all survive an attribute of the same name. Written as a plain lowercase attribute instead, a
class or a style is matched to the parameter of that name by the razor compiler
and never arrives as a splatted attribute at all.
Styled through the Style parameter
Classed through the Class parameter
A splatted class, kept beside the class and the alignment the component builds
RTL
Dir sets the direction of the text, writing the
dir attribute and, for right-to-left, the
bit-rtl class the rest of the library reads. The logical Align values follow it, so the
same Start that aligns to the left in a left-to-right page aligns to the right here without the
markup changing.
این یک عنوان راستچین است
این متن از لبهی آغازین چیده شده است.
این متن از لبهی پایانی چیده شده است.
API
Every parameter, public member, sub-class and enum this component exposes.
BitText 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 | Forces the text to always break at the end. |
| 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 | If true, the text will have a bottom margin, sized in em so that it follows the size of the variant. |
| 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 | If true, the text will not wrap, but instead will truncate with a text overflow ellipsis. |
| 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 of the text. |
| 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. |
| 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. |
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. |
| 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. |
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. |
BitColor enum
| Name | Value | Description |
|---|---|---|
| Primary | 0 | Info 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 an h6. The default variant. |
| Subtitle2 | 7 | Renders an h6. |
| 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. |
Feedback
Found a mistake, a gap, or something that could be clearer? Every page and every component is one click from its source.