Layouts
Header
Bit.BlazorUI
The BitHeader component renders a bar at the top of a site or an application, holding whatever belongs there: a brand, a navigation toggle, a search box or a row of account actions. It renders a semantic header element - the banner landmark of the page - and lays its content out in a horizontal line whose color, variant, size, alignment, wrapping, gutters, spacing and maximum width are all parameters. It can stay in the flow or be pinned to the top of the viewport, hiding itself while the page is scrolled down, lifting itself off the content once the page has left its top, or sliding out of the way on demand - and it carries the accessibility a pinned bar owes its users, from the skip link past it to the room it reserves so nothing scrolled to lands underneath it.
Usage
Every example is live. Open its code to see exactly what produced the component running underneath.
Basic
The header renders its content in a bar that is as tall as that content plus the paddings of its size. The Height parameter pins it to an exact height in pixels instead.
I'm a Header
I'm a Header with a fixed 80px height
I'm a disabled Header
Variant
The variant decides how the color of the header is painted: Fill (the default) uses it as the background,
Outline keeps the background transparent and draws a border in it, and Text keeps the background
transparent with no border, which lets the page show through the header.
Fill
Outline
Text
Alignment
The content of the header is a horizontal flex line, and Alignment decides how the free space of
that line is shared. SpaceBetween is the classic app bar: a brand on one edge and the account actions
on the other. Baseline and Stretch distribute nothing, so those two align the content on the
cross axis instead of the horizontal one.
Start
of
the line
Center
of
the line
End
of
the line
Space
between
the items
Space
around
the items
Space
evenly
around the items
VerticalAlign is the other axis: it decides where the content sits in the height of a header that is
taller than its content, which is what a header with an explicit Height or a stretched neighbour
needs. It is centered by default, and the three space distributions have no meaning here.
Top of the header
Middle of the header
Bottom of the header
Wrap
The content of the header is a single line by default, which squeezes every item once there is not enough
room for all of them. Wrap lets it break onto more lines instead, so a header that holds a brand, a
set of navigation links and a row of actions stays readable on a narrow screen. The lines are separated by
the row part of Gap and packed by VerticalAlign.
No wrap 1No wrap 2No wrap 3No wrap 4No wrap 5No wrap 6No wrap 7No wrap 8
Wrapped 1Wrapped 2Wrapped 3Wrapped 4Wrapped 5Wrapped 6Wrapped 7Wrapped 8
Border & elevation
Bordered draws a divider on the bottom edge of the header, and Elevated casts a shadow
downwards. Both separate the header from the content below it, which matters most when the header is pinned
over that content: a border is the flatter, quieter option and the shadow reads as the header floating above
the page.
Bordered
Elevated
Bordered & Elevated
Gutter
The content of the header sits in a container with paddings around it (the gutter). NoGutter removes
them, so the content can run edge to edge - for a full width progress bar, a toolbar of buttons or any content
bringing its own spacing.
With the default gutter:
With the default gutter
NoGutter:
Gap
The children of the header sit right next to each other by default. Gap puts space between them,
and it takes any CSS length (or the two value form of the gap shorthand) - so the same header works for a
tight row of icon buttons and for a widely spaced set of navigation links.
No
gap
at all
A
0.5rem
gap
A
2rem
gap
Max width
MaxWidth caps the content of the header and centers it, while the header itself keeps spanning
the full width - its background, its border and its shadow still run edge to edge. It is what lines a
bar up with a page body that is centered in a column of the same width, which is the layout of nearly
every documentation and marketing site. It takes any CSS length.
Full width content
Edge to edge
Capped at 24rem
And centered
Position
Sticky keeps the header in the flow but pins it to the top of the scrolling area once its own place in
the content has been passed, so it never covers anything. Fixed takes it out of the flow and anchors it
to the top of the page, which does overlap the content: reserve room for it at the start of the page.
Absolute is that same overlap scoped to a box - the header of a card, a panel or a dialog - and it needs
an ancestor with a position of its own to pin itself to. Only one position can win, and Fixed beats Absolute,
which beats Sticky.
The two that really sit at the top of the screen, Fixed and Sticky, also add the top safe area inset of the
device, so the header never lands under a status bar or a notch - and an explicit Height grows by that
inset instead of losing part of itself to it.
Sticky (scroll inside the box):
I'm a sticky Header
Row 1
Row 2
Row 3
Row 4
Row 5
Row 6
Row 7
Row 8
Row 9
Row 10
Row 11
Row 12
Fixed (scoped to the box below for the sake of the demo):
I'm a fixed Header
The fixed header covers the top of its page.
Absolute (pinned to the top of the box that holds it, with no scoping trick needed):
I'm an absolute Header
The absolute header covers the top of its container.
Reveal
Reveal hides a pinned header while the scroll goes down and slides it back in as soon as the scroll goes
up, so it gives the content the whole viewport while the user is reading and returns the moment they look for
it. It is always revealed at the very top of the scrolling area, and it needs Fixed or Sticky to
have anything to slide over. The OnRevealChanged callback reports every flip of that state, and the
read-only IsRevealed member holds it. A header that hides itself never strands a keyboard user either:
it comes back as soon as anything inside it takes the focus.
Scroll inside the box to hide and reveal the header: revealed
I hide myself while you scroll down
Row 1
Row 2
Row 3
Row 4
Row 5
Row 6
Row 7
Row 8
Row 9
Row 10
Row 11
Row 12
RevealOffset holds the header in place until the scroll has travelled that many pixels from the top,
which keeps it from flickering away on a scroll that has barely started:
I stay until you scroll past 100px
Row 1
Row 2
Row 3
Row 4
Row 5
Row 6
Row 7
Row 8
Row 9
Row 10
Row 11
Row 12
Elevate on scroll
A pinned header that is shadowed from the start looks detached from a page that has not moved yet.
ElevateOnScroll keeps it flat while the scrolling area sits at its top and fades the shadow in the
moment content starts passing underneath it, which is the whole "you are no longer at the top" signal in one
parameter. ElevateOffset decides how far the scroll has to travel first, and Elevated takes
precedence: a header that is always lifted has nothing left to gain from a scroll.
I gain my shadow once you scroll
Row 1
Row 2
Row 3
Row 4
Row 5
Row 6
Row 7
Row 8
Row 9
Row 10
Row 11
Row 12
The OnScrolledChanged callback reports the same flip, and the read-only IsScrolled member holds
it - which is what a header that has to do more than cast a shadow at that moment hooks into. Here it shrinks
the header and swaps its title for a compact one:
My Awesome Application
Row 1
Row 2
Row 3
Row 4
Row 5
Row 6
Row 7
Row 8
Row 9
Row 10
Row 11
Row 12
Scroll target
Both scroll behaviors need to know which box is doing the scrolling, and the header finds it on its own
by walking up from itself - which covers the page and any pane it sits inside. ScrollTarget names
that box with a CSS selector instead, for the app shell layout where the bar and the scrolling content
are siblings rather than one inside the other. A selector that matches nothing falls back to the walk,
so a target rendered later never leaves the header without a scrolling area at all.
The header below sits outside the scrolling pane, and reacts to it by name:
I react to the pane below me
Row 1
Row 2
Row 3
Row 4
Row 5
Row 6
Row 7
Row 8
Row 9
Row 10
Row 11
Row 12
Hidden
Hidden is the programmatic counterpart of Reveal: the header slides away because the application says
so rather than because the page is being scrolled, which is what a distraction free reading mode or a full
screen media view needs. Unlike Visibility, which switches the header off at once, it animates in and
out and keeps the room the header occupies. A hidden header is also marked inert, so none of its
buttons can be clicked or reached with the keyboard while it is out of the view.
Chapter 3
Translucent
Translucent softens the background of the header and blurs what passes behind it, so a pinned header
hints at the content it covers instead of cutting it off - the frosted glass of a native mobile bar. Only the
Fill variant has a background to soften.
I'm a translucent Header
Content behind the header - row 1
Content behind the header - row 2
Content behind the header - row 3
Content behind the header - row 4
Content behind the header - row 5
Content behind the header - row 6
Content behind the header - row 7
Content behind the header - row 8
Content behind the header - row 9
Content behind the header - row 10
Accessibility
The header renders a semantic header element, which the browser exposes as the banner landmark
of the page - the region screen reader users jump to for the brand, the global navigation and the account
actions. That mapping only holds while the element is not nested in an article, aside, main, nav or section,
so a page level header belongs outside of them.
A page is meant to expose that landmark once, so a second header (a toolbar, a bar that belongs to one pane)
needs an AriaLabel to tell the two apart when they are listed. There is no need to spell out the word
header in that label - the role is announced already.
A header is also the block of links every keyboard user has to walk through before they reach anything they
came for. SkipLinkHref renders the shortcut past it (WCAG 2.4.1, Bypass Blocks) as the very first
focusable element of the header, out of sight until it is focused, so it costs a sighted user nothing.
SkipLinkText changes its wording. Give the target a tabindex="-1" so the browser really moves
the focus there instead of only scrolling to it.
Click the header below and press Tab to bring the skip link into view:
Skip to main content
My Awesome App
The skip link lands here.
A pinned header also covers the top of the content, so anything the browser scrolls into view - a
control that has just taken the focus, the target of an anchor, a call to scrollIntoView - stops with
that thing hidden behind the bar (WCAG 2.4.11, Focus Not Obscured). ScrollPadding reserves the
height of the header at the top of the scrolling area, which is what makes those scrolls stop short of
it, and it keeps that reservation in step while the header changes size.
Click the first button of each box and hold Tab to walk down it:
Without ScrollPadding - the focus lands under me
With ScrollPadding - the focus stops below me
Usage
A complete application header: a navigation toggle and a brand on one side, the account actions on the other, with a BitSpacer pushing the two groups apart.
My Awesome App
Color
The general colors of the theme are all available, and each of them works with every variant. Without a color
the header keeps the primary background and foreground of the theme, which is what a page level header usually wants.
Primary
Secondary
Tertiary
Info
Success
Warning
SevereWarning
Error
PrimaryBackground
SecondaryBackground
TertiaryBackground
PrimaryForeground
SecondaryForeground
TertiaryForeground
PrimaryBorder
SecondaryBorder
TertiaryBorder
Size
The size sets the paddings around the content, which is what makes a header compact or roomy when its height is left to the content.
Small
Medium
Large
Style & Class
Style and Class reach the root element of the header, while Styles and Classes reach
each of its parts by name - the root, the container that holds the content, and the skip link.
Component's Style & Class:
Styled Header
Classed Header
Styles & Classes:
Styles
Classes
RTL
Use the Dir parameter to change the direction of the header, which flips the alignment of its content and the side its paddings sit on.
یک
دو
سه
API
Every parameter, public member, sub-class and enum this component exposes.
BitHeader parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| Absolute | bool | false | Renders the header with an absolute position at the top of its nearest positioned ancestor. Fixed takes precedence over it, and it takes precedence over Sticky. |
| Alignment | BitAlignment? | null | Gets or sets the horizontal distribution of the content of the BitHeader (the CSS justify-content of the container). Baseline and Stretch act on the cross axis (the vertical alignment) instead. |
| Bordered | bool | false | Renders a divider line on the bottom edge of the BitHeader to separate it from the content below. |
| ChildContent | RenderFragment? | null | Gets or sets the content to be rendered inside the BitHeader. |
| Classes | BitHeaderClassStyles? | null | Custom CSS classes for different parts of the BitHeader. |
| Color | BitColor? | null | The general color of the BitHeader. It is applied through the Variant: as the background color in the Fill variant, and as the text and border color in the Outline and Text variants. |
| ElevateOffset | int? | null | Gets or sets how far (in pixels) the scroll has to travel from the top before an ElevateOnScroll header lifts itself off the content. |
| ElevateOnScroll | bool | false | Keeps the BitHeader flat while the scrolling area sits at its top and lets it cast its shadow only once the content has been scrolled underneath it. It only has an effect on a Fixed or Sticky header, and Elevated takes precedence over it. |
| Elevated | bool | false | Renders the BitHeader with a shadow cast downwards, to lift it above the content it overlaps. |
| Fixed | bool | false | Renders the header with a fixed position at the top of the page. It takes precedence over Absolute and Sticky when more than one of them is set. |
| Gap | string? | null | Gets or sets the space between the children of the BitHeader (the CSS gap of the container). It takes any CSS length or the two value form of the gap shorthand. |
| Height | int? | null | Gets or sets the height of the BitHeader (in pixels). The height includes the paddings and the border of the header, and a header that really sits at the top of the screen (Fixed, or Sticky without an Absolute outranking it) adds the top safe area inset of the device on top of it. |
| Hidden | bool | false | Slides the BitHeader out of the view, and brings it back when it is turned off again. A hidden header is also marked inert, so nothing inside it can be clicked or reached with the keyboard while it is out of the view. |
| MaxWidth | string? | null | Gets or sets the maximum width of the content of the BitHeader, which is then centered in the header. The header itself keeps spanning the full width, so its background, its border and its shadow still run edge to edge. |
| NoGutter | bool | false | Removes the default paddings around the content of the BitHeader, so it can span the full width of the header. |
| OnRevealChanged | EventCallback<bool> | Callback for when the reveal state of the header changes. The provided value is true when the header is revealed. Only invoked while Reveal is enabled. | |
| OnScrolledChanged | EventCallback<bool> | Callback for when the scrolled state of the header changes. The provided value is true once the scrolling area has travelled past the ElevateOffset. Only invoked while ElevateOnScroll is enabled. | |
| Reveal | bool | false | Slides the header out of the view while the page is scrolled down and brings it back while the page is scrolled up. It only has an effect on a Fixed or Sticky header, since the others have nothing to slide over. |
| RevealOffset | int? | null | Gets or sets how far (in pixels) the scroll has to travel from the top before a Reveal header starts hiding itself. The header stays revealed while the scroll is still within this offset. |
| ScrollPadding | bool | false | Reserves the height of the BitHeader at the top of the scrolling area, so nothing scrolled to - the target of an anchor, a control that has just taken the focus, a call to scrollIntoView - lands underneath a pinned header (WCAG 2.4.11). It only has an effect on a Fixed or Sticky header. |
| ScrollTarget | string? | null | Gets or sets the CSS selector of the element whose scrolling drives the BitHeader. By default the header finds its own scrolling area by walking up from itself, and a selector that matches nothing falls back to that walk. |
| Size | BitSize? | null | The size of the BitHeader, which determines the paddings around its content. |
| SkipLinkHref | string? | null | Gets or sets the target of the skip link of the BitHeader, which is what makes it render at all. It is rendered as the very first focusable element of the header and stays out of sight until it is focused. |
| SkipLinkText | string? | null | Gets or sets the text of the skip link of the BitHeader. It defaults to "Skip to main content" and is only rendered when a SkipLinkHref is provided. |
| Sticky | bool | false | Renders the header with a sticky position at the top of the viewport. Unlike Fixed, it keeps the room it occupies in the layout, so nothing has to be reserved for it, and it only covers the content once that content scrolls up to it. |
| Styles | BitHeaderClassStyles? | null | Custom CSS styles for different parts of the BitHeader. |
| Translucent | bool | false | Softens the background of the BitHeader and blurs what passes behind it, for the frosted glass look of a header pinned over scrolling content. Only the Fill variant has a background to soften. |
| Variant | BitVariant? | null | The visual variant of the BitHeader. |
| VerticalAlign | BitAlignment? | null | Gets or sets the vertical alignment of the content of the BitHeader (the CSS align-items of the container). Only Start, End, Center, Baseline and Stretch align a line on the cross axis, so the three space distributions are ignored here. |
| Wrap | bool | false | Lets the content of the BitHeader wrap onto more than one line instead of being squeezed into a single one. The lines are packed by VerticalAlign and separated by the row part of Gap. |
BitHeader public members
| Name | Type | Default value | Description |
|---|---|---|---|
| IsRevealed | bool | true | Gets a value indicating whether the header is currently revealed. It reports the scroll driven reveal state alone, so it is always true unless Reveal is enabled, and stays true for a header slid out of the view with Hidden. |
| IsScrolled | bool | false | Gets a value indicating whether the scrolling area of the header has travelled past the ElevateOffset. It is always false unless ElevateOnScroll is enabled. |
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. |
BitHeaderClassStyles properties
| Name | Type | Default value | Description |
|---|---|---|---|
| Root | string? | null | Custom CSS classes/styles for the root element of the BitHeader. |
| Container | string? | null | Custom CSS classes/styles for the container element of the BitHeader that wraps its content. |
| SkipLink | string? | null | Custom CSS classes/styles for the skip link of the BitHeader, which is only rendered when a SkipLinkHref is provided. |
BitAlignment enum
| Name | Value | Description |
|---|---|---|
| Start | 0 | Packs the content at the start of the line, or at the top of the header. |
| End | 1 | Packs the content at the end of the line, or at the bottom of the header. |
| Center | 2 | Packs the content at the center of the line, or in the middle of the header. |
| SpaceBetween | 3 | Distributes the free space between the items, with no space at the two edges. Ignored by VerticalAlign. |
| SpaceAround | 4 | Distributes the free space around the items, so the edges get half of what sits between the items. Ignored by VerticalAlign. |
| SpaceEvenly | 5 | Distributes the free space evenly between the items and at the two edges. Ignored by VerticalAlign. |
| Baseline | 6 | Aligns the content on its baseline (the cross axis of the header). |
| Stretch | 7 | Stretches the content to the full height of the header (the cross axis). |
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. |
BitVariant enum
| Name | Value | Description |
|---|---|---|
| Fill | 0 | Fill styled variant. |
| Outline | 1 | Outline styled variant. |
| Text | 2 | Text styled variant. |
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.