Skip to content
BlazorUI

Utilities

Text

Bit.BlazorUITypography

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.

Usage

Every example is live. Open its code to see exactly what produced the component running underneath.

Basic

Typography picks a step of the theme's type ramp - size, weight, line height and tracking - and the tag: the headings render h1-h6, the subtitles a div - they are not headings - the body variants and Inherit a p, the rest a span. The default is Subtitle1; Inherit takes everything from the element around it.

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 sets the tag apart from the look: an h2 drawn as an h4 keeps the page outline right. It also reaches tags no variant maps to - strong, blockquote, code. An invalid tag name falls back to the variant's tag; a void tag such as hr renders without content.

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)

Weight & emphasis

Weight moves along the theme's weight scale. Italic, Underline and Strikethrough combine freely. Transform changes the case on screen only - a copy and a screen reader get the original text. Where emphasis carries meaning, use an Element such as em, strong or del.

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

Numbers & monospace

Numeric uses tabular, lining figures, so digits line up in a column and a changing number does not jitter; letters stay proportional. Monospace switches to the theme's monospaced family for code, IDs and hashes - pair it with a code, kbd or samp Element to carry the meaning too.

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 };

Truncation

NoWrap keeps the text on one line and ends it with an ellipsis; LineClamp does the same after N lines. Both need a box with a width: Block gives one to an inline variant such as a caption. The full text stays in the document for copy, find and screen readers - a title (splatted onto the element) shows it to pointer users too.

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.

Wrapping

BreakWord breaks only a word that cannot fit - a URL, a path - and lets a flex or grid item shrink below its longest word; ForceBreak breaks anywhere. Wrap picks how lines break: Balance for short headings, Pretty for body copy. Hyphenate needs a page language the browser has a dictionary for. PreserveWhitespace keeps written line breaks and spaces.

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.

Align

Align aligns the lines inside the box. Start and End follow the text direction; Left and Right do not. Avoid Justify on long text - its uneven word spacing is harder to read.

Start
Center
End
Justify. Once upon a time, stories wove connections between people, a symphony of voices crafting shared dreams.

Gutter & trim

Gutter adds a bottom margin in em, so it scales with the variant. Trim removes the space the line height adds above the cap height (Start), below the baseline (End) or both, so the gap you set is the gap you get. Browsers without text-box-trim ignore it.

A heading with a gutter

A paragraph with a smaller gutter

A paragraph with none

None

Start

End

Both

Foreground & gradient

Foreground uses the theme's neutral text colors - Secondary and Tertiary recede beside body copy. Gradient paints the glyphs with any CSS background-image value. Both give the text its system color back in forced-colors mode; check the contrast at both ends of a gradient.

Primary foreground
Secondary foreground
Tertiary foreground

A gradient headline

A radial gradient

Body text fading out into nothing

Accessibility

AriaLevel sets the announced heading level without changing the tag or the look, adding role="heading" to a non-heading tag. VisuallyHidden hides text from view but not from screen readers, and shows it again while the keyboard focus is in it - tab to the skip link below, a BitLink inside a visually hidden text. Lang switches the screen reader's voice. NoSelect is for chrome text, not content.

A div announced as a level 3 heading

An h2 announced as a level 4 heading

Read out by a screen reader, drawn nowhere.
Bonjour tout le monde
This text cannot be selected

Visibility & disabled

Visibility hides the text, keeping or dropping its space, and takes it out of the accessibility tree too - VisuallyHidden is the one that keeps it there. Disabled dims the text and keeps its paint; forced-colors mode paints it in GrayText.

Visible: [Visible text]
Hidden: []
Collapsed: []
Disabled text
Disabled text, keeping its gradient

Cascading parameters

BitParams with a BitTextParams sets defaults for every text inside it. A parameter set on a text itself always wins.

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

Color

Color applies one of the library's color roles. Do not let color alone carry a meaning, and check the contrast of the background and border roles, which are meant for text on other surfaces.

Primary
Secondary
Tertiary
Info
Success
Warning
SevereWarning
Error
PrimaryBackground
SecondaryBackground
TertiaryBackground
PrimaryForeground
SecondaryForeground
TertiaryForeground
PrimaryBorder
SecondaryBorder
TertiaryBorder

Style & Class

Style and Class are merged with what the component builds, as are a class and a style splatted through @attributes. The --bit-Text-* CSS variables restyle every text under the element they are set on, or every text when set on :root; an explicit parameter still wins.

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

RTL

Dir sets the text direction; the logical Align values follow it.

این یک عنوان راست‌چین است
این متن از لبه‌ی آغازین چیده شده است.
این متن از لبه‌ی پایانی چیده شده است.

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.

BitText CSS variables

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.

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 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.

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.

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.

Feedback

Found a mistake, a gap, or something that could be clearer? Every page and every component is one click from its source.