Skip to main content

Panel

Overview​

The Panel component implements Bulma's versatile panel block for React.

It provides a convenient way to display lists, filters, navigation menus, or grouped actions in a card-like vertical container. The Panel supports color modifiers, search, tabs, icons, selectable blocks, and comes with several subcomponents for every panel part.

info

Use Panel for sidebar menus, filter lists, admin navigation, or any grouped interface actions.


Import​

import { Panel } from '@allxsmith/bestax-bulma';

Usage​

Complete Panel (Revolutionary Figures)​

This example shows a complete panel layout using Panel and its subcomponents. The Panel.Heading provides a title, Panel.InputBlock adds a search field, and Panel.Tabs enables filtering. Use Panel.Block for each item, with active on the current one, and Panel.Icon to display icons. This structure is ideal for sidebars, filter lists, or admin menus. The color prop customizes the panel's appearance. The panel takes its name from its heading through aria-labelledby, and role="heading" with an aria-level makes the heading one, at the level that fits the headings around it.

<Panel aria-labelledby="panel-figures">
  {/* The level that fits the headings around the panel: 4 here, under an h3. */}
  <Panel.Heading id="panel-figures" role="heading" aria-level={4}>
    Revolutionary Figures
  </Panel.Heading>
  <Panel.InputBlock placeholder="Search figures" />
  <Panel.Tabs>
    <a href="#all" className="is-active" aria-current="true">
      All
    </a>
    <a href="#patriots">Patriots</a>
    <a href="#loyalists">Loyalists</a>
    <a href="#battles">Battles</a>
    <a href="#documents">Documents</a>
  </Panel.Tabs>
  <Panel.Block href="#george-washington" active>
    <Panel.Icon name="user" variant="solid" />
    George Washington
  </Panel.Block>
  <Panel.Block href="#alexander-hamilton">
    <Panel.Icon name="user" variant="solid" />
    Alexander Hamilton
  </Panel.Block>
  <Panel.Block href="#benedict-arnold">
    <Panel.Icon name="user" variant="solid" />
    Benedict Arnold
  </Panel.Block>
  <Panel.Block href="#john-adams">
    <Panel.Icon name="user" variant="solid" />
    John Adams
  </Panel.Block>
  <Panel.Block href="#battle-of-saratoga">
    <Panel.Icon name="flag" variant="solid" />
    Battle of Saratoga
  </Panel.Block>
  <Panel.Block href="#treaty-of-paris">
    <Panel.Icon name="flag" variant="solid" />
    Treaty of Paris
  </Panel.Block>
  <Panel.Block href="#bunker-hill">
    <Panel.Icon name="flag" variant="solid" />
    Bunker Hill
  </Panel.Block>
  <Panel.CheckboxBlock>remember me</Panel.CheckboxBlock>
  <Panel.ButtonBlock>Reset all filters</Panel.ButtonBlock>
</Panel>


Color Variants​

This example demonstrates the Panel component's color variants. The color prop applies Bulma's color modifiers to the panel. Each panel in this example uses a different color, showcasing the flexibility of the Panel component in adapting to various design requirements.

<>
  {(
    [
      'primary',
      'link',
      'info',
      'success',
      'warning',
      'danger',
      'black',
      'dark',
      'light',
      'white',
    ] as const
  ).map(color => (
    <Panel key={color} color={color} aria-labelledby={`panel-${color}`}>
      <Panel.Heading id={`panel-${color}`}>
        {color.charAt(0).toUpperCase() + color.slice(1)} Panel
      </Panel.Heading>
      <Panel.InputBlock placeholder="Search figures" />
      <Panel.Block href="#george-washington" active>
        <Panel.Icon name="user" variant="solid" />
        George Washington
      </Panel.Block>
      <Panel.Block href="#marquis-de-lafayette">
        <Panel.Icon name="user" variant="solid" />
        Marquis de Lafayette
      </Panel.Block>
      <Panel.Block href="#nathanael-greene">
        <Panel.Icon name="user" variant="solid" />
        Nathanael Greene
      </Panel.Block>
      <Panel.Block href="#battle-of-trenton">
        <Panel.Icon name="flag" variant="solid" />
        Battle of Trenton
      </Panel.Block>
      <Panel.Block href="#yorktown">
        <Panel.Icon name="flag" variant="solid" />
        Yorktown
      </Panel.Block>
      <Panel.ButtonBlock>Reset all filters</Panel.ButtonBlock>
    </Panel>
  ))}
</>


A Panel That Is Not Navigation​

Panel renders a <nav>, a navigation landmark, which suits a panel of links. For one that is not navigation, as renders it as an article (Bulma's own colored panels use one), a section, an aside or a div. A section is a region landmark once it has an accessible name, here its heading through aria-labelledby. Panel.Block renders an <a> unless as says div or label: a div block holds content that is not a link, such as a table.

<Panel as="section" color="info" aria-labelledby="panel-sessions">
  <Panel.Heading id="panel-sessions">Congress Sessions</Panel.Heading>
  <Panel.Block as="div">
    <Table isFullwidth>
      <Table.Thead>
        <Table.Tr>
          <Table.Th>Date</Table.Th>
          <Table.Th>Session</Table.Th>
        </Table.Tr>
      </Table.Thead>
      <Table.Tbody>
        <Table.Tr>
          <Table.Td>1774</Table.Td>
          <Table.Td>First Continental Congress</Table.Td>
        </Table.Tr>
        <Table.Tr>
          <Table.Td>1775</Table.Td>
          <Table.Td>Second Continental Congress</Table.Td>
        </Table.Tr>
      </Table.Tbody>
    </Table>
  </Panel.Block>
  <Panel.Block href="#delegates">
    <Panel.Icon name="user" variant="solid" />
    All delegates
  </Panel.Block>
</Panel>


A Search Field With a Name of Its Own​

Panel.InputBlock's field takes its name from its placeholder, and has none without one, so give it one that says what it searches. Attributes you pass for the field, aria-label, aria-labelledby and id among them, go on the block around it. For a field with a name of its own, build the block from Panel.Block as="div" with a Control and an Input inside, and give the Input its aria-label, and an id or anything else the field needs.

<Panel aria-labelledby="panel-repositories">
  <Panel.Heading id="panel-repositories">Repositories</Panel.Heading>
  <Panel.Block as="div">
    <Control iconLeftName="search">
      <Input aria-label="Search repositories" placeholder="Search" />
    </Control>
  </Panel.Block>
  <Panel.Block href="#bulma">
    <Panel.Icon name="book" variant="solid" />
    bulma
  </Panel.Block>
  <Panel.Block href="#marksheet">
    <Panel.Icon name="book" variant="solid" />
    marksheet
  </Panel.Block>
</Panel>


Compound (dot-notation) usage​

Every subcomponent is exported by name (PanelHeading, PanelBlock, …) and attached to Panel as a static, so a whole panel can be composed from the single Panel import.

<Panel aria-labelledby="panel-documents">
  <Panel.Heading id="panel-documents">Founding Documents</Panel.Heading>
  <Panel.Block href="#declaration-of-independence" active>
    <Panel.Icon name="file" variant="solid" />
    Declaration of Independence
  </Panel.Block>
  <Panel.Block href="#articles-of-confederation">
    <Panel.Icon name="file" variant="solid" />
    Articles of Confederation
  </Panel.Block>
  <Panel.ButtonBlock>Reset all filters</Panel.ButtonBlock>
</Panel>


Accessibility​

  • The root panel renders as a semantic <nav>, a navigation landmark, by default. For a panel that is not navigation, set as to article, section, aside or div, and give a section an accessible name (for example aria-labelledby pointing at the Panel.Heading's id) if it should be a region.
  • Panel.Heading renders Bulma's <p class="panel-heading">, which assistive tech reads as a plain paragraph: it isn't a heading, and it doesn't name the panel. A screen reader user who moves by heading skips it, and one who moves by landmark hears "navigation" for each panel with nothing to tell them apart. Give the heading role="heading" and the aria-level that fits the headings already on the page. To name a nav panel, the default, after its heading, give the heading an id that's unique on the page and write aria-labelledby with that id on the Panel, the way the bullet above names a section. The examples above name each panel this way, and the first also makes its heading one.
  • The Panel.Block by default renders as an anchor <a>. Its props follow as: only an a takes the anchor attributes (href, target, download and the rest), and only a label takes htmlFor and form. A block on another tag drops them, and rel, at runtime too.
  • Give each Panel.Block that opens something an href, as the examples do: an <a> with no href isn't a link, so Tab skips it, Enter does nothing on it, and assistive tech reads it as text. A block that isn't a link takes as="div", or as="label" around a control. The links you write in Panel.Tabs take an href too, and the active one aria-current="true" beside its is-active class, which is only seen.
  • Panel.InputBlock's field takes its name from its placeholder, which browsers fall back to, and an aria-label you pass it names nothing. A Search Field With a Name of Its Own shows what to pass and how to build a field with a name of its own.
  • Panel.Block active sets aria-current="page" on the element as renders, the <a> by default, so the current block isn't only a color. An aria-current you pass wins: a panel of sections on one page can say "location", and aria-current={false} turns it off, as on an active label block with a checkbox.
  • A panel with no color keeps its heading readable on the dark scheme through bestax's components/panel partial, which extras.css and bestax.css include. Bulma's CSS alone writes that heading white on light gray.
  • A panel with a color draws the text of its active block and active tab, the active block's icon and the active tab's underline in that color at the lightness Bulma picks for the color's text on the page, through the same partial, so they read on both schemes. Black takes the title text's lightness, which is white on the dark scheme. Without the partial the text inherits the color's text helper Panel puts on the panel, and the icon and underline take the color's own lightness, which for a light or white panel is near white on white.
  • Forced colors: Bulma marks the active tab and the active block with colors alone, which forced colors (Windows' contrast themes) replaces, so bestax's styles draw a bar in the system's highlight color there: along the bottom of the active tab, and down the start edge of the active block. The tab, the block and everything in them stay in the contrast theme's colors. It reads the is-active class, on a Panel.Block and on the tab links you write in Panel.Tabs. The panel's own edge is a shadow, which forced colors drops, so the same styles draw it as a one pixel line in the system's text color around the panel, with a line under the heading in place of its fill. This comes from the same partial.

  • Icon: For icons inside Panel.Icon.
  • Helper Props: Bulma helper props for spacing and other utilities.

Additional Resources​

Pro Tip

You can use Bulma helper props with <Panel /> and Panel.Icon for powerful utility-based styling.


Props​

PropTypeDefaultDescription
as'nav' | 'article' | 'section' | 'aside' | 'div''nav'HTML element to render (default: nav). A nav is a navigation landmark, which suits a panel of links; a panel that is not navigation takes another tag. Bulma's own colored panels use article. A section is a region landmark only once it has an accessible name, such as aria-labelledby pointing at the id of its Panel.Heading.
color'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger' | 'black' | 'dark' | 'light' | 'white'—Bulma color modifier for the panel. With none, the heading takes the text color, with its title in the page background's color so it reads on both schemes. On the dark scheme that title color comes from bestax's stylesheets: Bulma's CSS alone writes it white on light gray there. With a color, the active block's and active tab's text, the active block's icon and the active tab's underline take it at the lightness Bulma picks for the color's text on the page, also from bestax's stylesheets, so they read on both schemes. Black takes the title text's lightness, which is white on the dark scheme. With a colorShade, the text takes that shade and the icon and underline the color's own lightness, as Bulma draws them.
classNamestring—Additional CSS classes.
childrenReact.ReactNode—Panel content (usually includes subcomponents).
...All standard HTML attributes and Bulma helper props—See Helper Props

Subcomponents:

  • Panel.Heading: The panel's title: a paragraph to assistive tech, until you give it role="heading" and an aria-level. It renders Bulma's <p class="panel-heading">, which doesn't name the panel either. Pick the level that fits the headings already on the page, so screen reader users can move to it by heading. To name the panel after it, give it an id that's unique on the page and write aria-labelledby with that id on the Panel: two nav panels, the default, are then two navigation landmarks a screen reader can tell apart.
  • Panel.Tabs: Panel tabs (renders as <p class="panel-tabs">). Its links are yours to write. Give each an href, so the keyboard can reach it, and the active one aria-current="true" beside its is-active class, which is only seen.
  • Panel.Block: Individual panel block (renders as <a class="panel-block"> unless as says otherwise). Give a block that opens something an href: an <a> with no href isn't a link, so Tab skips it. A block that isn't a link takes as="div", or as="label" around a control.
  • Panel.Icon: Icon wrapper with panel styling (renders as <span class="panel-icon">, containing an <i/> when a name is given, or the custom node passed as children). Accepts all Icon props (name, variant, features, etc.), or children for a custom node.
  • Panel.InputBlock: Search input with icon (renders as <div class="panel-block"> around the <input>). Its field takes its name from its placeholder, which browsers fall back to, and has none without one, so pass one that says what it searches. Attributes you pass for the field, aria-label, aria-labelledby and id among them, go on the div, not on the <input>, and name nothing there. For a field that needs a name of its own, an id or other input attributes, build the block from <Panel.Block as="div"> with a Control and an Input inside.
  • Panel.CheckboxBlock: Checkbox block (renders as <label class="panel-block">)
  • Panel.ButtonBlock: Call-to-action button (renders as <div class="panel-block"><button /></div>)

Panel.Heading​

PropTypeDefaultDescription
classNamestring—Additional CSS classes.
childrenReact.ReactNode—Heading content.
...All standard <p> attributes—

Panel.Tabs​

PropTypeDefaultDescription
classNamestring—Additional CSS classes.
childrenReact.ReactNode—Tabs content.
...All standard <div> attributes—

Panel.Block​

PropTypeDefaultDescription
as'a' | 'div' | 'label''a'HTML element to render (default: a). Bulma styles a label block as clickable, like an a, and a div block as static content, such as a table. The props follow the tag, so the anchor attributes (href, target, download and the rest) are typed only on an a and htmlFor only on a label; at runtime the block also drops them, and rel, on the other tags. Panel.CheckboxBlock, Panel.InputBlock and Panel.ButtonBlock render the usual label and div blocks with their contents.
classNamestring—Additional CSS classes.
activebooleanfalseMarks the block as the current one. It adds Bulma's is-active class, and aria-current="page" on the element as renders, so assistive tech can tell which block is current too. An aria-current you pass wins, even undefined: use it to say something else ("location" for a section of one page, say), or aria-current={false} to turn it off, as on an active block that isn't navigation, such as a label with a checkbox.
childrenReact.ReactNode—Block content.
...Remaining props of the element selected by as (default <a>)—

Panel.Icon​

PropTypeDefaultDescription
namestring—The icon name, with or without its library prefix (e.g. 'star' or 'fa-star'). Mutually exclusive with children.
childrenExclude<React.ReactNode, undefined>—A custom node (an inline SVG, a react-icons component, …) rendered inside the icon container in place of a class-based glyph. Mutually exclusive with name.
iconstring—Deprecated. Use name instead. Legacy icon class string (e.g. 'fas fa-star'). Only its last segment is read, as the glyph name; the library still comes from library or ConfigProvider, so 'mdi mdi-rocket' renders an fa class unless the effective library is already mdi — set it here or on the provider.
classNamestring—Additional CSS classes to apply.
textColorBulma color | 'inherit' | 'current'—Text color helper.
color'primary' | 'link' | 'info' | 'success' | 'warning' | 'danger'—Text color alias: renders has-text-<color>, exactly like textColor. Not a filled variant (no .icon.is-<color> CSS exists). Prefer textColor, which takes precedence when both are set; use bgColor for a colored surface.
bgColorBulma color | 'inherit' | 'current'—Background color helper.
library'fa' | 'mdi' | 'ion' | 'material-icons' | 'material-symbols''fa'The icon library to use ('fa' = Font Awesome, 'mdi' = Material Design Icons, 'ion' = Ionicons Web Components, 'material-icons' = Google Material Icons, 'material-symbols' = Google Material Symbols). Defaults to the value set in ConfigProvider or 'fa' if not configured. Ignored when children supplies the glyph instead of name.
variantstring—Icon style variant (e.g. 'solid', 'outlined', 'rounded'). Ignored when children supplies the glyph instead of name.
featuresstring | string[]—Additional modifiers (e.g. 'fa-lg', 'fa-spin', 'is-size-1'). Ignored when children supplies the glyph instead of name.
libraryFeaturesstring | string[]—Deprecated. Use variant and features instead. Additional modifiers in the older combined form, parsed into variant and features.
size'small' | 'medium' | 'large'—Size modifier for the icon container.
ariaLabelstring—Accessible name for an icon that means something on its own. Set it and the container span gets role="img" with this aria-label, so the name is exactly this text: a Material ligature such as rocket_launch inside stays out of it. Leave it unset (or empty) and the icon is decorative: the span renders aria-hidden="true" and no name, so it adds nothing to the accessible name of a Button or text around it. For an icon-only control, put the name on the control (e.g. Button's aria-label) and leave this unset. A non-empty native aria-label or aria-labelledby passed instead also counts as a name, and an explicit role or aria-hidden wins over both defaults. An unnamed icon given a role or a tabIndex of its own isn't hidden, since hiding something focusable is a failure of its own, so give it a name: without one, a Material ligature's text or an SVG inside it can name it, or the control around it, and a development build warns. For Ionicons the <ion-icon> inside is always aria-hidden, so it adds no image of its own.
styleReact.CSSProperties—Inline style object.
...All standard <span> attributes and Bulma helper props—See Helper Props

Panel.InputBlock​

PropTypeDefaultDescription
valuestring—Input value.
onChangeReact.ChangeEventHandler<HTMLInputElement>—Input change handler.
placeholderstring—The field's placeholder, which browsers fall back to for its name, so say what it searches ("Search repositories").
iconClassNamestring'fas fa-search'Icon class for left icon (default 'fas fa-search').
classNamestring—Additional CSS classes, added to the block's own panel-block class.
...All standard <div> attributes—

Panel.CheckboxBlock​

PropTypeDefaultDescription
checkedbooleanfalseWhether the checkbox is checked.
onChangeReact.ChangeEventHandler<HTMLInputElement>—Checkbox change handler.
childrenReact.ReactNode—Label/content.
classNamestring—Additional CSS classes, added to the block's own panel-block class.
...All standard <label> attributes—

Panel.ButtonBlock​

PropTypeDefaultDescription
childrenReact.ReactNode—Button content.
classNamestring—Additional CSS classes, added to the button's own. Like the block's other props, it goes on the <button>, not on the panel-block around it.
...All standard <button> attributes—

CSS & Sass Variables​

Panel registers these variables on its own .panel element. Override them there (or via className) — a value set on an ancestor is only inherited, and loses to the component-level declaration. See Theme.

CSS VariableSass VariableDefault
--bulma-text-invert-l$panel-text-invert-lvar(--bulma-scheme-main-l)
--bulma-panel-margin$panel-marginvar(--bulma-block-spacing)
--bulma-panel-item-border$panel-item-border1px solid var(--bulma-border-weak)
--bulma-panel-radius$panel-radiusvar(--bulma-radius-large)
--bulma-panel-shadow$panel-shadowvar(--bulma-shadow)
--bulma-panel-heading-line-height$panel-heading-line-height1.25
--bulma-panel-heading-padding$panel-heading-padding1em 1.25em
--bulma-panel-heading-radius$panel-heading-radiusvar(--bulma-radius)
--bulma-panel-heading-size$panel-heading-size1.25em
--bulma-panel-heading-weight$panel-heading-weightvar(--bulma-weight-bold)
--bulma-panel-tabs-font-size$panel-tabs-font-size1em
--bulma-panel-tab-border-bottom-color$panel-tab-border-bottom-colorvar(--bulma-border)
--bulma-panel-tab-border-bottom-style$panel-tab-border-bottom-stylesolid
--bulma-panel-tab-border-bottom-width$panel-tab-border-bottom-width1px
--bulma-panel-tab-active-color$panel-tab-active-colorvar(--bulma-link-active)
--bulma-panel-list-item-color$panel-list-item-colorvar(--bulma-text)
--bulma-panel-list-item-hover-color$panel-list-item-hover-colorvar(--bulma-link)
--bulma-panel-block-color$panel-block-colorvar(--bulma-text-strong)
--bulma-panel-block-hover-background-color$panel-block-hover-background-colorvar(--bulma-background)
--bulma-panel-block-active-border-left-color$panel-block-active-border-left-colorvar(--bulma-link)
--bulma-panel-block-active-color$panel-block-active-colorvar(--bulma-link-active)
--bulma-panel-block-active-icon-color$panel-block-active-icon-colorvar(--bulma-link)
--bulma-panel-icon-color$panel-icon-colorvar(--bulma-text-weak)
--bulma-panel-h—var(--bulma-scheme-h)
--bulma-panel-s—var(--bulma-scheme-s)
--bulma-panel-color-l—var(--bulma-text-l)
--bulma-panel-heading-background-l—var(--bulma-text-l)
--bulma-panel-heading-color-l—var(--bulma-text-invert-l)

Bulma points --bulma-panel-block-active-color and --bulma-panel-tab-active-color at --bulma-link-active, which it never defines, so they have no value. On a panel with a color, bestax's components/panel partial gives the active block and active tab a fallback for them, the color at its on-scheme lightness, and sets --bulma-panel-color-l, which Bulma draws the active icon and the active tab's underline from, to that lightness. A value of your own for the two active colors, set on the panel, still wins, and so does a --bulma-panel-color-l set through the panel's style.