Skip to content
BlazorUI

Surfaces

Accordion

Bit.BlazorUIExpander

The Accordion shows and hides a section of content behind a header. The header is a button inside a heading, wired to its panel the way the WAI-ARIA accordion pattern asks; the panel animates to its content's height, can be found by find-in-page while closed, and the whole component is driven by binding, events or its Expand, Collapse and Toggle methods.

Usage

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

Basic

Title names the header; everything inside the component is the panel. Description adds a quieter second line, IconName (or Icon) a leading glyph, and DefaultIsExpanded opens it on the first render. Each accordion keeps its own state - for one collection driving many (one open at a time, arrow keys), use BitAccordionList.

Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.

Expander icon

ExpanderIconName / ExpanderIcon replace the chevron, ExpanderIconPosition moves it to the start, HideExpanderIcon removes it and NoExpanderRotation keeps it still. ExpandedExpanderIconName swaps it while open, which also stops the rotation.

Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.

Actions

Actions render beside the header, outside the toggle button and its heading, so they can hold buttons of their own - a button inside the header would be a button nested in a button. Once the accordion holds more than its panel, the panel goes in Body, the named alias of the content written straight inside it.

Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.

Binding

@bind-IsExpanded keeps the state and a field in step both ways. IsExpanded bound one way makes the accordion controlled: it never moves on its own, and OnClick is where the page decides - here, one open at a time. IsEnabled="false" ignores pointer and keyboard, while the binding still drives it.

Two-way:
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.


Controlled (one open at a time):
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.

Events

OnClick reports every click on the header; OnChange, OnExpand and OnCollapse report a change that happened. OnToggling runs before it and can refuse it with Cancel; it is awaited (the header reports busy meanwhile) and says why through IsExpanding and Reason.


Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.

Clicks: 0, last OnChange: False
Expanded: 0, collapsed: 0, refused: 0

Programmatic control

Expand, Collapse and Toggle report through the binding and events like a click (and work on a disabled accordion). FocusAsync moves the keyboard to the header; a panel that closes on the focus hands it back to its header on its own.



Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.

Content rendering

The panel is rendered while closed by default, keeping its state. LazyContent waits for the first expand, then keeps it; UnmountOnCollapse drops it on every collapse (no closing animation). Type into both, then close and reopen them. To fetch the content first, await it in OnToggling: the panel opens once it is loaded, and the header shows a spinner (and aria-busy) meanwhile. Busy shows the same for work the page runs itself.

MaxHeight & Transition

MaxHeight (any CSS length) caps the open panel and scrolls its content; the scroll region takes a tab stop. TransitionDuration (ms) overrides the theme's duration, 0 turns it off. Reduced motion turns it off too, unless ForceAnimation is set.

Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams. These placeholder words symbolize the beginning - a moment of possibility where creativity has yet to take shape. Imagine this text as the scaffolding of something remarkable, a foundation upon which connections and inspirations will be built. Soon, these lines will transform into narratives that provoke thought, spark emotion, and resonate with those who encounter them. This space is yours to craft, yours to shape.
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.

Find & print

A closed panel is skipped by find-in-page and prints as a bare header. HiddenUntilFound hands it to the browser as hidden="until-found": Ctrl+F or a #fragment link finds text inside and the accordion expands around the match (OnToggling sees Reason = Reveal). ExpandOnPrint opens it on paper only (Ctrl+P), lifting MaxHeight. Both need the panel in the DOM: HiddenUntilFound overrides LazyContent and UnmountOnCollapse, while content they left out cannot print.

Search the page for tangerine, or open the print preview:

Returns are free within thirty days of delivery.

Templates

TitleTemplate replaces the title text, ExpanderTemplate the expander (still rotated unless NoExpanderRotation), and HeaderTemplate the whole header. All three render inside the toggle button, so anything interactive belongs in Actions.

Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.

Read-only

ReadOnly is the panel that must stay as it is (e.g. the last open one): it keeps its colors and tab stop, reports aria-disabled, still raises OnClick and still answers the methods. Compare IsEnabled="false", which greys it out and drops the tab stop.

Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.

Accessibility

The header is a button in a heading, named by the Title and described by the Description; the panel is a region it controls. HeadingLevel sets the heading depth (3 by default; nested accordions go one deeper on their own). A closed panel is out of the tab order and the accessibility tree. HeaderAriaLabel names an icon-only header, AriaLabel names the accordion as a group, and NoContentRegion drops the landmark role for pages with many open panels.

Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.

Cascading parameters

BitParams with a BitAccordionParams sets defaults for every accordion inside it. An accordion's own parameters win; only unset ones are filled in. A cascaded HeadingLevel reaches top-level accordions only.

Color

Background and Border pick the color kind of the surface and the outline (Transparent lets the underlying surface show). NoBorder drops the outline and fills with the secondary background.

Background:
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.


Border:
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.


NoBorder:
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.

External Icons

Icon, ExpanderIcon and ExpandedExpanderIcon take a BitIconInfo, so any CSS icon library works: a bare class string or BitIconInfo.Css, or the BitIconInfo.Fa / BitIconInfo.Bi shortcuts.

FontAwesome:
ExpanderIcon=@("fa-solid fa-chevron-down")
Icon="@BitIconInfo.Fa("solid gear")"


Bootstrap:
ExpanderIcon="@BitIconInfo.Css("bi bi-chevron-down")"
Icon="@BitIconInfo.Bi("gear")"

Size

Size scales the padding and the type of the whole accordion - header, icons and panel.

Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.

Style & Class

Reach for the --bit-Accordion-* CSS variables first (listed in the API section): they inherit, so set them on :root, an ancestor or an instance's Style. Style/Class and Styles/Classes (per part; Expanded and ExpandedIcon apply only while open) cover the rest.

CSS variables:
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.


Style & Class:
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.
Styles & Classes:
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.
Every story starts with a blank canvas, a quiet space waiting to be filled with ideas, emotions, and dreams.

RTL

Dir="BitDir.Rtl" (or a cascaded one) mirrors the header: the icon leads from the right, the expander closes on the left.

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

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.

BitAccordion CSS variables

Name Default value Description
--bit-Accordion-color --bit-clr-fg-pri Text color of the accordion.
--bit-Accordion-background Per Background, --bit-clr-bg-pri (--bit-clr-bg-sec with NoBorder) Fill of the accordion. The Background parameter wins over it.
--bit-Accordion-border-color Per Border, --bit-clr-brd-pri Color of the outline. The Border parameter wins over it.
--bit-Accordion-border-width --bit-shp-brd-width Thickness of the outline.
--bit-Accordion-radius --bit-shp-radius-surface Corner radius of the accordion, which the header and the panel follow.
--bit-Accordion-shadow none Elevation of the accordion (e.g. var(--bit-shd-card)).
--bit-Accordion-font-size Per Size, --bit-tpg-fs-xs/sm/md Text size of the panel and the description.
--bit-Accordion-header-padding Per Size Padding of the header (any padding shorthand).
--bit-Accordion-header-hover-background Per Background, its hover shade Fill of the header under the pointer.
--bit-Accordion-header-active-background The hover fill, then the Background's active shade Fill of the header while pressed.
--bit-Accordion-header-expanded-background transparent Fill of the header while the accordion is expanded; once set, the hover and pressed shades no longer replace it.
--bit-Accordion-header-expanded-color inherit Text of the header while the accordion is expanded. The title, icon and expander colors win over it; nested accordions do not inherit it.
--bit-Accordion-title-color inherit Color of the title.
--bit-Accordion-title-font-size Per Size, --bit-tpg-fs-sm/md/lg Size of the title.
--bit-Accordion-title-font-weight --bit-tpg-fw-semibold Weight of the title.
--bit-Accordion-description-color --bit-clr-fg-sec Color of the description.
--bit-Accordion-icon-size Per Size, --bit-siz-icon-sm/md/lg Size of the icon, of the expander icon and of the busy spinner.
--bit-Accordion-icon-color inherit Color of the icon at the start of the header.
--bit-Accordion-expander-color inherit Color of the expander icon (or of the ExpanderTemplate content) and of the busy spinner.
--bit-Accordion-content-padding Per Size Padding of the open panel (any padding shorthand); its block padding animates from 0.
--bit-Accordion-content-background transparent Fill of the panel, drawn over the accordion's own fill.
--bit-Accordion-divider-color transparent Rule between the header and the open panel, as thick as the outline.
--bit-Accordion-focus-color --bit-clr-pri-focus Keyboard focus ring of the header and of a scrolling panel.
--bit-Accordion-disabled-color --bit-clr-fg-dis Text of a disabled accordion.
--bit-Accordion-disabled-background --bit-clr-bg-dis Fill of a disabled accordion.

API

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

BitAccordion parameters

Name Type Default value Description
Actions RenderFragment? null The content rendered beside the header, outside of the toggle button and of the heading it sits in, so that it can hold its own interactive elements (a menu, a delete button, a switch).
Background BitColorKind? null The color kind of the background of the accordion. Wins over an inherited --bit-Accordion-background.
Border BitColorKind? null The color kind of the border of the accordion. Wins over an inherited --bit-Accordion-border-color.
Body RenderFragment? null Alias for the ChildContent parameter.
Busy bool false Reports the header as busy - a spinner in the expander's slot, aria-busy and a busy cursor, and no click toggles it - while something the page is doing on the accordion's behalf is still running. An accordion whose own OnToggling is being awaited reports itself as busy without being told to.
Classes BitAccordionClassStyles? null Custom CSS classes for different parts of the accordion.
ChildContent RenderFragment? null The content of the accordion.
DefaultIsExpanded bool? null Default value for the IsExpanded parameter.
Description string? null A short description in the header of the accordion.
ExpandedExpanderIcon BitIconInfo? null Gets or sets the icon to show in place of the expander icon while the accordion is expanded, using custom CSS classes for external icon libraries. Takes precedence over ExpandedExpanderIconName when both are set. Setting either of them also turns the rotation of the expander icon off.
ExpandedExpanderIconName string? null Gets or sets the name of the icon, from the built-in Fluent UI icons, to show in place of the expander icon while the accordion is expanded. Setting it also turns the rotation of the expander icon off.
ExpanderIcon BitIconInfo? null Gets or sets the icon to display as expander using custom CSS classes for external icon libraries. Takes precedence over ExpanderIconName when both are set. Defaults to the ChevronRight icon if neither property is set.
ExpanderIconName string? null Gets or sets the name of the icon to display as expander from the built-in Fluent UI icons. Defaults to ChevronRight if not set.
ExpanderIconPosition BitIconPosition? null Gets or sets the side of the header the expander icon sits on. The default value is End.
ExpanderTemplate RenderFragment<bool>? null Custom content in place of the expander icon, receiving the expanded state. It still turns over unless NoExpanderRotation is set, and HideExpanderIcon still removes it; HeaderTemplate replaces it with the rest of the header.
ExpandOnPrint bool false Opens the panel on paper, so a collapsed section is not printed as a bare header, and lifts the MaxHeight scroll cap. Content not in the DOM (a never-opened LazyContent panel, a collapsed UnmountOnCollapse one) still cannot print.
HeaderAriaLabel string? null Gets or sets the accessible label of the toggle button in the header, for a header whose own content does not name it - an icon-only HeaderTemplate, most of all.
HeaderTemplate RenderFragment<bool>? null Used to customize the header of the accordion. It replaces the whole default header, the expander icon included, and receives the current expanded state.
HeadingLevel int? null Gets or sets the heading level (aria-level) reported for the header of the accordion, so that it takes its right place in the heading outline of the page. The default value is 3 - or one level below the accordion this one is nested in - and the value is clamped to the 1..6 range.
HiddenUntilFound bool false Hands the collapsed panel to the browser as hidden="until-found", so find-in-page and a navigation to a fragment inside it reach the text and expand the accordion around the match (reported to OnToggling with the Reveal reason). The panel stays in the DOM, so LazyContent and UnmountOnCollapse are ignored; a disabled, read-only or one-way bound accordion is not offered to find-in-page.
HideExpanderIcon bool false Removes the expander icon from the header of the accordion.
Icon BitIconInfo? null Gets or sets the icon to display at the start of the header using custom CSS classes for external icon libraries. Takes precedence over IconName when both are set.
IconName string? null Gets or sets the name of the icon to display at the start of the header from the built-in Fluent UI icons.
IsExpanded bool false Determines whether the accordion is expanded or collapsed. (two-way bound)
LazyContent bool false Delays the first render of the content of the accordion until it is expanded for the first time. The content stays in the DOM afterwards, so the state it holds survives a collapse. Ignored while HiddenUntilFound is on.
MaxHeight string? null Gets or sets the maximum height of the content of the accordion (any CSS length), beyond which the content scrolls inside the accordion instead of growing it. The scrolling region is focusable, so that it can be scrolled by the keyboard as well.
NoBorder bool false Removes the default border of the accordion and gives a background color to the body.
NoContentRegion bool false Removes the region role (a landmark) from the panel, leaving a plain container. The WAI-ARIA authoring practices ask for it where more than about six panels can be open at once, so the landmarks do not flood the page.
NoExpanderRotation bool false Keeps the expander icon still instead of turning it over when the accordion is expanded.
OnClick EventCallback<MouseEventArgs> Callback that is called when the header is clicked.
OnChange EventCallback<bool> Callback that is called when the IsExpanded value has changed.
OnCollapse EventCallback Callback that is called when the accordion is collapsed.
OnExpand EventCallback Callback that is called when the accordion is expanded.
OnToggling EventCallback<BitAccordionToggleArgs> Called before the accordion expands or collapses; set Cancel to refuse the change. It is awaited, so it can load the panel's content or ask for a confirmation first, and the header reports busy meanwhile. A change made through the IsExpanded parameter itself is not offered here.
ReadOnly bool false Leaves the accordion where it is: the header keeps its colors and its place in the tab order, and reports itself as aria-disabled, but it no longer answers the pointer or the keyboard. OnClick still reports the click, and the Expand, Collapse and Toggle methods still drive the accordion.
Size BitSize? null Gets or sets the size of the accordion, which drives the padding of the header and of the panel and the type scale of the whole component. The default value is Medium.
Styles BitAccordionClassStyles? null Custom CSS styles for different parts of the accordion.
Title string? null Title in the header of the accordion, which also names the header button and the panel for assistive technologies (the Description describes them).
TitleTemplate RenderFragment? null The custom content to render in place of the Title, leaving the rest of the header - the icon, the description and the expander - as it is. Unlike HeaderTemplate, which replaces the whole header, this only takes the place of the title text.
TransitionDuration int? null Gets or sets the duration of the expand/collapse transition in milliseconds, overriding the duration the theme provides. A reduced-motion preference still collapses it, unless the ForceAnimation parameter opts out of that.
UnmountOnCollapse bool false Removes the content of the accordion from the DOM while it is collapsed, so that nothing it holds keeps running behind a closed header. The collapse of an accordion that unmounts its content is not animated, since there is nothing left to animate. Ignored while HiddenUntilFound is on.

BitAccordion public members

Name Type Default value Description
Expand Task Expands the accordion. Does nothing if it is already expanded, and reports the change through the IsExpanded binding, OnChange and OnExpand.
Collapse Task Collapses the accordion. Does nothing if it is already collapsed, and reports the change through the IsExpanded binding, OnChange and OnCollapse.
Toggle Task Expands the accordion if it is collapsed and collapses it if it is expanded, reporting the change through the IsExpanded binding, OnChange and OnExpand/OnCollapse.
FocusAsync ValueTask Gives the focus to the header of the accordion, so that a panel the app has just opened is also where the keyboard is standing. The overload taking a bool prevents the header from being scrolled into view.

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.

BitAccordionToggleArgs properties

Name Type Default value Description
IsExpanding bool The state the accordion is about to move to: true while it is expanding, false while it is collapsing.
Reason BitAccordionToggleReason What made the accordion expand or collapse: a click on its header, a call to one of its Expand, Collapse and Toggle methods, or a find-in-page match the browser revealed.
Cancel bool false Set to true to cancel the expansion or the collapse and leave the accordion as it is.

BitAccordionClassStyles properties

Name Type Default value Description
Root string? null Custom CSS classes/styles for the root element of the BitAccordion.
Expanded string? null Custom CSS classes/styles for the expanded state of the BitAccordion.
HeaderWrapper string? null Custom CSS classes/styles for the header wrapper of the BitAccordion, which holds the heading and the actions.
Heading string? null Custom CSS classes/styles for the heading element of the BitAccordion that wraps the header button.
Header string? null Custom CSS classes/styles for the header of the BitAccordion.
Icon string? null Custom CSS classes/styles for the icon at the start of the header of the BitAccordion.
HeaderContent string? null Custom CSS classes/styles for the header content of the BitAccordion.
Title string? null Custom CSS classes/styles for the title of the BitAccordion.
Description string? null Custom CSS classes/styles for the description of the BitAccordion.
ExpanderIconWrapper string? null Custom CSS classes/styles for the expander icon wrapper of the BitAccordion.
ExpanderIcon string? null Custom CSS classes/styles for the expander icon of the BitAccordion.
ExpandedIcon string? null Custom CSS classes/styles for the icon of the BitAccordion in expanded state.
Spinner string? null Custom CSS classes/styles for the spinner that stands in the expander's slot while the BitAccordion is busy.
Actions string? null Custom CSS classes/styles for the actions of the BitAccordion, rendered beside the header.
ContentContainer string? null Custom CSS classes/styles for the content container of the BitAccordion.
ContentWrapper string? null Custom CSS classes/styles for the content wrapper of the BitAccordion, which clips the content while it collapses.
Content string? null Custom CSS classes/styles for the content of the BitAccordion.

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.

BitIconPosition enum

Name Value Description
Start 0 Icon renders before the content.
End 1 Icon renders after the content (default).

BitAccordionToggleReason enum

Name Value Description
Click 0 The header of the accordion was clicked, or activated by the Enter or the Space key.
Method 1 The Expand, Collapse or Toggle method of the accordion was called.
Reveal 2 The browser revealed the collapsed panel of a HiddenUntilFound accordion, because find-in-page or a navigation to a fragment landed inside it.

BitSize enum

Name Value Description
Small 0 The small size.
Medium 1 The medium size.
Large 2 The large size.

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.