Skip to content
BlazorUI

Layouts

Header

Bit.BlazorUI

BitHeader is the bar at the top of a site or an application (an app bar): a semantic header element - the banner landmark - holding a brand, navigation and actions in one line, with an optional second row for tabs. It can be pinned to the top, hide on scroll down, elevate once scrolled, slide away on demand, and carries a skip link and scroll padding for keyboard users.

Usage

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

Basic

As tall as its content plus the paddings of its size; Height fixes it in pixels.

I'm a Header

I'm a Header with a fixed 80px height

I'm a disabled Header

Variant

Fill (default) paints the color as the background, Outline as a border, Text as the text only.

Fill

Outline

Text

Border & elevation

Bordered draws a bottom divider, Elevated casts a shadow - both separate the header from the content below it.

Bordered


Elevated


Bordered & Elevated

Alignment

Alignment distributes the content along the line (SpaceBetween is the classic brand-left, actions-right bar). VerticalAlign places it in the height of the header (centered by default).

Start of the line

Center of the line

End of the line

Space between the items

VerticalAlign: Start

VerticalAlign: End

Layout

Gap spaces the children (any CSS length), Wrap lets them break onto more lines on a narrow screen, NoGutter removes the paddings, and MaxWidth caps and centers the content while the surface stays full width.

Gap:
A 0.5rem gap

Wrap:
Wrapped 1Wrapped 2Wrapped 3Wrapped 4Wrapped 5Wrapped 6Wrapped 7Wrapped 8

NoGutter:

MaxWidth:
Capped at 24rem And centered

Extension

ExtensionContent adds a second row under the main one - tabs, a search box, a breadcrumb - sharing the surface and the scroll behaviors of the header, and lining up with the main row's gutter and MaxWidth.

Project Atlas

Position

Sticky stays in the flow and pins once scrolled to. Fixed leaves the flow and overlaps the top of the page. Absolute overlaps the top of its nearest positioned ancestor (a card, a panel). Fixed beats Absolute, which beats Sticky. Fixed and Sticky add the device's top safe area inset, on top of any Height.

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:

I'm an absolute Header
The absolute header covers the top of its container.

Reveal

Reveal hides a Fixed or Sticky header while scrolling down and brings it back on scroll up or when anything inside it takes the focus - and keeps it while it holds the keyboard focus. RevealOffset keeps it until the scroll has passed that many pixels. OnRevealChanged and IsRevealed report the state.

Scroll inside the box: 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


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

ElevateOnScroll keeps a pinned header flat at the top and fades its shadow in once content scrolls under it (after ElevateOffset pixels). OnScrolledChanged and IsScrolled expose the same state - here to shrink the header and swap its title.

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


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

The header finds its scrolling area by walking up from itself. ScrollTarget names it with a CSS selector instead, for an app shell whose bar and content pane are siblings. A selector that matches nothing falls back to the walk.

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 slides the header away on demand (an immersive or reading mode). Unlike Visibility it animates and keeps its room, and the hidden header is inert, so none of its controls can be reached.

Chapter 3

Translucent

Translucent softens the Fill background and blurs what scrolls behind it - the frosted glass of a native mobile bar.

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 is the page's banner landmark (when not nested in main, article, aside, nav or section). A second one - a toolbar, a pane's bar - needs an AriaLabel to tell them apart.



SkipLinkHref renders a skip link (WCAG 2.4.1) as the first focusable element, visible only on focus; SkipLinkText rewords it. Give the target tabindex="-1" so the focus really moves there. Click the header and press Tab:

Skip to main content
My Awesome App
The skip link lands here.


ScrollPadding reserves the height of a pinned header at the top of its scrolling area, so a focused control or an anchor target never ends up underneath it (WCAG 2.4.11). Click the first button in each box and hold Tab:

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, a BitSpacer, then the account actions.

My Awesome App

Cascading parameters

BitParams hands a BitHeaderParams to every header under it as defaults: a header keeps whatever it sets itself and only takes what it left unset.

Takes the color, the variant, the size and the border from the cascade

Its own Color, the cascaded rest

Outside the cascade, and back to the defaults

Color

Every theme color works with every variant. Without one the header keeps the theme's primary background and foreground.

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.

Small

Medium

Large

Style & Class

Reach for the --bit-Header-* CSS variables first (listed in the API section): they inherit, so set them on :root, an ancestor or an instance's Style. Style/Class reach the root, and Styles/Classes each part (root, container, extension, skip link).

CSS variables:

On the instance

On an ancestor

Every header under it follows

Style & Class:

Styled Header

Classed Header

Styles & Classes:

Styles

Classes

RTL

Dir mirrors the header: the alignment of its content and the side its paddings sit on.

یک دو سه

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 that one alone. Leave a variable unset and the component falls back to the theme token beside it.

BitHeader CSS variables

Name Default value Description
--bit-Header-background The Color kind (--bit-clr-bg-pri) Fill of the Fill variant.
--bit-Header-color The Color kind (--bit-clr-fg-pri) Color of the content.
--bit-Header-border-color The Color kind (--bit-clr-brd-pri) Border of the Outline variant, and the divider of a Bordered header.
--bit-Header-border-width --bit-shp-brd-width Thickness of that border and divider.
--bit-Header-border-radius 0 Corners of the surface, for a floating header inset from the edges of its page or card.
--bit-Header-padding-block The Size Room above and below the main row. NoGutter outranks it.
--bit-Header-padding-inline The Size Room on the two sides of both rows. NoGutter outranks it.
--bit-Header-min-height 0 Minimum height of the main row (for example the 64px of a Material top app bar).
--bit-Header-gap 0 Space between the children of the main row. The Gap parameter outranks it.
--bit-Header-max-width none Maximum width of the content of both rows. The MaxWidth parameter outranks it.
--bit-Header-shadow --bit-shd-appbar-top Shadow of an Elevated header, or of an ElevateOnScroll one once scrolled.
--bit-Header-z-index --bit-zin-base Stacking order of a Fixed, Sticky or Absolute header.
--bit-Header-backdrop-blur 12px Blur of what passes behind a Translucent header.
--bit-Header-translucent-opacity 72% How much of its fill a Translucent header keeps.
--bit-Header-disabled-color The Color kind (--bit-clr-fg-dis) Content color of a disabled header, and the border of a disabled Outline one.
--bit-Header-disabled-background The Color kind (--bit-clr-bg-pri) Fill of a disabled Fill header.
--bit-Header-skip-link-color --bit-clr-pri-text Text color of the focused skip link.
--bit-Header-skip-link-background --bit-clr-pri Fill of the focused skip link.

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.
ExtensionContent RenderFragment? null Gets or sets the content of a second row rendered under the main row of the BitHeader, such as a row of tabs, a search box or a breadcrumb. It shares the surface and the scroll behaviors of the header, takes the same inline gutter and MaxWidth as the main row, and has no block padding of its own.
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. It is the exact height of a header with no ExtensionContent, and a minimum height of one with an ExtensionContent row, so the two rows together can grow the header past it rather than being clipped. 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 comes back when anything inside it takes the focus, and stays while it holds the keyboard focus. 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.
Extension string? null Custom CSS classes/styles for the second row of the BitHeader, which is only rendered when an ExtensionContent is provided.
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.