Skip to content
BlazorUI

Surfaces

Collapse

Bit.BlazorUI

Collapse opens and closes a section of a page. It renders no trigger of its own, so anything can drive it, and it animates the real size of its content - downwards or sideways, all the way or down to a peek. Closed content leaves the tab order and the accessibility tree yet stays reachable by find-in-page, and expensive content can stay out of the DOM until it is opened.

Notes

The transition honors the reduced motion preference of the OS/browser (prefers-reduced-motion) and finishes at once, whatever Duration says. If nothing on this page animates, turn that setting off, or use the ForceAnimation parameter or the ForceAnimation toggle at the top of this page.

Usage

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

Basic

Expanded opens and closes the section. The collapse draws no trigger, so whatever flips the value lives on the page beside it, and the size follows the content, however late it loads or wraps.


In the beginning, there is silence a blank canvas yearning to be filled, a quiet space where creativity waits to awaken. These words are temporary, standing in place of ideas yet to come, a glimpse into the infinite possibilities that lie ahead. Think of this text as a bridge, connecting the empty spaces of now with the vibrant narratives of tomorrow. It whispers of the stories waiting to be told, of the thoughts yet to be shaped into meaning, and the emotions ready to resonate with every reader.

Binding & control

@bind-Expanded keeps the state on the page, DefaultExpanded leaves it to the component, and ExpandAsync, CollapseAsync and ToggleAsync drive it through a reference. OnChange reports the changes the component makes itself. A disabled collapse (Disabled) keeps its state, ignores the three methods and takes the disabled colors.


The button and the collapse share one value: True.


Starts open through DefaultExpanded; nothing on the page holds its state.

Padding & background

The collapse pads its content and paints the primary background. NoPadding removes the padding for content with insets of its own, and Background picks another color kind, Transparent included.




Default: padding and the primary background.

Secondary background.

Transparent, no padding: the content carries its own surface and insets.

Horizontal

Horizontal opens the section sideways from the start edge, at the width of its content - a collapsing sidebar, a search box growing out of its icon, a row of toolbar actions.


This panel opens sideways.

Collapsed size

CollapsedSize (any CSS length, padding included) leaves a peek of the content on the page - a "show more" clamp. A peek keeps its opacity and stays readable by assistive technology; on a Horizontal collapse it is a width.


In the beginning, there is silence a blank canvas yearning to be filled, a quiet space where creativity waits to awaken. These words are temporary, standing in place of ideas yet to come, a glimpse into the infinite possibilities that lie ahead. Think of this text as a bridge, connecting the empty spaces of now with the vibrant narratives of tomorrow. It whispers of the stories waiting to be told, of the thoughts yet to be shaped into meaning, and the emotions ready to resonate with every reader.
In this space, potential reigns supreme. It is a moment suspended in time, where imagination dances freely and each word has the power to transform into something extraordinary. Here lies the start of something new-an opportunity to craft, inspire, and create.

Transition

Duration, Delay (ms) and Easing (any CSS timing function) retune the transition; ExpandDuration and CollapseDuration retune one direction. NoFade leaves the size to do the work alone, and NoAnimation removes the transition.




Duration="1000" Delay="200" and an overshooting Easing
A thousand milliseconds after a two hundred millisecond wait.

ExpandDuration="900" CollapseDuration="200"
Opens slowly, closes quickly.

NoFade
The content never changes its opacity.

NoAnimation
Appears and disappears at once.

Transition events

OnExpanding / OnCollapsing fire as the transition starts, OnExpanded / OnCollapsed when the transition the browser actually played has ended - whatever set its pace - which is the moment to scroll to, measure or focus the section. All four report every change; a collapse's initial state reports none.


The -ing callback lands at once; the -ed one six hundred milliseconds later.

Overflow

The collapse clips its content so the transition reads as a section opening. NoClip stops clipping once it has finished opening, so a focus ring, a shadow or a dropdown menu inside it is drawn in full.




Default: the glow is cut off at the edge.


NoClip: the glow is drawn in full once the section is open.

Rendering & printing

LazyRender builds the content on the first open, and UnmountOnCollapse drops it once the close has played - losing whatever it held. ExpandOnPrint prints a closed section open (try print preview) and keeps its content in the DOM for it.




LazyRender

UnmountOnCollapse

ExpandOnPrint
On paper this section is always open.

Find in page

HiddenUntilFound lets find-in-page and fragment links reach into a closed section: the browser opens it around the match and the change is reported like any other. Its content stays in the DOM; a collapse that cannot open (disabled, or a one-way Expanded) is not offered to the search.


The passphrase kept in this section is marmalade skies. Close the section, press Ctrl+F and search for it.

Accessibility

Closed content leaves the tab order and the accessibility tree. The trigger is yours: a button with a fixed label, aria-expanded and aria-controls set to ContentId (the root's id + -content), which BitToggleButton renders through AriaMode="Expanded" and AriaControls. LabelledBy or AriaLabel names the region; an empty Role drops the role and the name. An open region is a tab stop (TabIndex="-1" takes it out) and FocusAsync moves the focus into it, best from OnExpanded. A section closed from inside hands the focus back to its trigger from OnCollapsing.


Orders placed before 2 pm ship the same day. Read the full policy.


FocusAsync put the focus here at the end of the expand transition.

Cascading parameters

BitParams with a BitCollapseParams sets defaults for every collapse under it; a collapse's own value wins (the last one keeps its padding). The state, the content, the callbacks and LabelledBy are not cascaded.




Secondary background, no padding, a slower pace.

The same, from the same BitParams.

Keeps its own padding.

Style & Class

Style and Class land on the root; Styles and Classes reach its parts: Root, the Expanded / Collapsed states of the root, the Content region and the padded Wrapper.




A styled root.

Styles for the expanded root and the wrapper.

Classes for the expanded root and the wrapper.

RTL

A vertical collapse is unchanged by the direction; a horizontal one opens from the start edge, the right in RTL.


لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ و با استفاده از طراحان گرافیک است. چاپگرها و متون بلکه روزنامه و مجله در ستون و سطرآنچنان که لازم است و برای شرایط فعلی تکنولوژی مورد نیاز و کاربردهای متنوع با هدف بهبود ابزارهای کاربردی می باشد.

این بخش از سمت راست باز می شود.

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.

BitCollapse CSS variables

Name Default value Description
--bit-Collapse-color --bit-clr-fg-pri Color of the text.
--bit-Collapse-background --bit-clr-bg-pri Background of the section. The Background parameter wins over it.
--bit-Collapse-padding spacing(1.5) (12px) Room between the edges of the section and its content. NoPadding wins over it.
--bit-Collapse-font-size --bit-tpg-fs-sm Size of the text.
--bit-Collapse-focus-color --bit-clr-pri-focus Color of the focus ring of the content region.
--bit-Collapse-duration --bit-mot-duration-long Pace of the expand/collapse transition. Duration, ExpandDuration and CollapseDuration win over it, and reduced motion collapses it unless ForceAnimation is set.
--bit-Collapse-easing --bit-mot-easing Timing function of the transition. The Easing parameter wins over it.
--bit-Collapse-peek-fade unset Length of the fade on the trailing edge of a closed CollapsedSize peek, which shows there is more to read. No fade by default.

API

Every parameter, public member, sub-class and enum this component exposes.

BitCollapse parameters

Name Type Default value Description
Background BitColorKind? null The color kind of the background of the collapse.
Body RenderFragment? null Alias for the ChildContent parameter.
ChildContent RenderFragment? null The content of the collapse.
Classes BitCollapseClassStyles? null Custom CSS classes for different parts of the collapse.
CollapseDuration int? null The duration of the collapse transition in ms, which overrides Duration while the collapse is closing and leaves the opening alone.
CollapsedSize string? null The size the collapse keeps while it is collapsed, as any CSS length, which leaves a peek of the content on the page instead of closing it all the way. It is a width instead of a height while Horizontal is on.
DefaultExpanded bool? null The default value of the Expanded parameter, applied once at initialization and only while Expanded itself has not been set.
Delay int? null The delay of the expand/collapse transition in ms.
Duration int? null The duration of the expand/collapse transition in ms. Leaving it unset keeps the duration of the motion theme (or --bit-Collapse-duration). The reduced motion preference still collapses it unless ForceAnimation is set. OnExpanded, OnCollapsed, NoClip, HiddenUntilFound and UnmountOnCollapse wait for the transition the browser actually plays.
Easing string? null The timing function of the expand/collapse transition, as any CSS easing value.
ExpandDuration int? null The duration of the expand transition in ms, which overrides Duration while the collapse is opening and leaves the closing alone.
Expanded bool false Determines whether the collapse is expanded or collapsed.
ExpandedChanged EventCallback<bool> The callback of the two-way binding of the Expanded parameter, raised with the new state.
ExpandOnPrint bool false Prints the collapse expanded, whatever its state on the screen. Such a collapse ignores LazyRender and UnmountOnCollapse, since the content has to be in the DOM to be printed.
HiddenUntilFound bool false Hands the closed content to the browser as hidden="until-found", so find-in-page and a navigation to a fragment inside the section reach into it and open it. Such a collapse ignores LazyRender and UnmountOnCollapse, since the content has to stay in the DOM to be found, and one that cannot open - disabled, or with a one-way Expanded - is not offered to find-in-page at all.
Horizontal bool false Collapses the content along the inline axis instead of the block one, so it opens sideways from the start edge.
LabelledBy string? null The id of the element that names the content region of the collapse, rendered as aria-labelledby.
LazyRender bool false Keeps the content out of the DOM until the collapse is expanded for the first time. A collapse that keeps a CollapsedSize, is searchable through HiddenUntilFound or prints expanded through ExpandOnPrint ignores it.
NoAnimation bool false Removes the expand/collapse transition, so the content appears and disappears at once.
NoClip bool false Stops clipping the content once the collapse has finished opening, so a focus ring, a shadow or a menu that reaches past the edges of the section is drawn in full. The clipping is put back the moment the collapse starts closing.
NoFade bool false Removes the fade of the content, leaving the size on its own to open and close the collapse.
NoPadding bool false Removes the padding the collapse puts around its content.
OnChange EventCallback<bool> Callback that is called when the Expanded value has changed by the component itself.
OnCollapsed EventCallback Callback that is called once the collapse has finished closing, which is the end of the collapse transition.
OnCollapsing EventCallback Callback that is called as the collapse starts closing, which is the start of the collapse transition. It is the place to move the focus back to the trigger when it is inside the section, since the closed content can no longer hold it.
OnExpanded EventCallback Callback that is called once the collapse has finished opening, which is the end of the expand transition.
OnExpanding EventCallback Callback that is called as the collapse starts opening, which is the start of the expand transition.
Role string? null The ARIA role of the content region of the collapse, which is region by default. An empty string renders no role at all, and with it no aria-label or aria-labelledby, since ARIA prohibits naming an element with no role - as it does under none, presentation and generic, which drop the name the same way.
Styles BitCollapseClassStyles? null Custom CSS styles for different parts of the collapse.
UnmountOnCollapse bool false Takes the content back out of the DOM once the collapse has closed, after the transition has had time to finish. A collapse that keeps a CollapsedSize, is searchable through HiddenUntilFound or prints expanded through ExpandOnPrint ignores it.

BitCollapse public members

Name Type Default value Description
ContentId string The id of the content element of the collapse, which is the id of the root element with -content after it, so a trigger elsewhere on the page can point its aria-controls at the section it opens.
CollapseAsync Task Collapses the collapse, reporting the change through ExpandedChanged and OnChange.
ExpandAsync Task Expands the collapse, reporting the change through ExpandedChanged and OnChange.
FocusAsync ValueTask Moves the focus to the content region of the collapse, which is focusable while it is on the screen, even when a TabIndex of -1 takes it out of the tab order. Worth pairing with OnExpanded so the focus lands once the section has finished opening.
ToggleAsync Task Flips the collapse between expanded and collapsed, reporting the change through ExpandedChanged and OnChange.

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.

BitCollapseClassStyles properties

Name Type Default value Description
Root string? null Custom CSS classes/styles for the root element of the BitCollapse.
Expanded string? null Custom CSS classes/styles for the root element of the BitCollapse in the expanded state.
Collapsed string? null Custom CSS classes/styles for the root element of the BitCollapse in the collapsed state.
Content string? null Custom CSS classes/styles for the content region of the BitCollapse, which is the element that fades between the two states and clips what is outside the collapsed size.
Wrapper string? null Custom CSS classes/styles for the wrapper the BitCollapse puts around its content, which is the element that carries the padding.

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.

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.