Panes · envUI Docs

Import

import { Panes, readPanesWidth } from '@envsemble/envui';

Usage

Panes.Root takes a behavior: supporting holds Panes.Main and Panes.Supporting, such as a document and its details, and list-detail holds Panes.List and Panes.Detail, such as messages and the one chosen, each pair with an optional Panes.Divider between them.

Below splitAt, the supporting pane is a modal sheet over the main one while open, and a list-detail shows the detail instead of the list while open.
Left uncontrolled, with defaultOpen, Panes.Trigger opens the sheet and people close it; a list-detail application keeps open itself, setting it as an item is chosen.
onOpenChange receives the new state and why: true with trigger-press, and false as people close it, with escape-key, close-press, outside-press for the backdrop, or back-press for the back button that returns to the list.

SupportingPane.tsx

import { useState } from 'react';
import { Column, DescriptionList, Panes, Text } from '@envsemble/envui';
import { IconInfo } from '@envsemble/envui/icons/Info';

export default function SupportingPane() {
  const [open, setOpen] = useState(false);
  return (
    // Side by side from an expanded width of their own; narrower, the details are a sheet over
    // the document, which the button opens and Escape closes.
    <Panes.Root
      behavior="supporting"
      open={open}
      onOpenChange={setOpen}
      style={{ blockSize: '18rem' }}
    >
      <Panes.Main label="Document">
        <Column gap={3} padding={4} align="start">
          <Text variant="title" render={<h3 />}>
            Quarterly report
          </Text>
          <Text>Revenue grew in every region, led by the new subscriptions.</Text>
          <Panes.Trigger variant="secondary" startIcon={<IconInfo />}>
            Details
          </Panes.Trigger>
        </Column>
      </Panes.Main>
      <Panes.Supporting label="Details">
        <Column gap={3} padding={4}>
          <DescriptionList.Root aria-label="About the report">
            <DescriptionList.Item label="Owner">Sam Lee</DescriptionList.Item>
            <DescriptionList.Item label="Due">31 March 2026</DescriptionList.Item>
          </DescriptionList.Root>
        </Column>
      </Panes.Supporting>
    </Panes.Root>
  );
}

Names and buttons

Panes.Supporting and Panes.List take a label, which names their region; on Panes.Main and Panes.Detail it is optional, and makes the pane a region landmark, for the panes of a page's main layout.

Panes.Trigger is a Button, primary by default, that opens the supporting sheet and hides while the panes sit side by side.
closeLabel names the sheet's close button, and backLabel the back button: name where it goes, such as Inbox.
Set aria-current on the list's current row.

<Panes.Root behavior="list-detail" open={open} onOpenChange={setOpen} backLabel="Inbox">
  <Panes.List label="Inbox">
    <Surface padding={2} style={{ minBlockSize: '100%' }}>
      <List.Root aria-label="Messages">…</List.Root>
    </Surface>
  </Panes.List>
  <Panes.Divider label="Resize the inbox" />
  <Panes.Detail label={chosen.subject}>
    <Surface padding={4} style={{ minBlockSize: '100%' }}>
      …
    </Surface>
  </Panes.Detail>
</Panes.Root>

Side by side

splitAt is the window class of the Panes' own width from which they sit side by side: medium, 37.5 rem, expanded, 52.5 rem and the default, or large, 75 rem. CSS decides it, so the server's markup is already right.

Resizable

Panes.Divider, named by its label, Resize panes by default, resizes the supporting pane or the list, by pointer and the arrow keys; a double click returns it to defaultWidth, 22.5 rem by default.

It stays between minWidth and maxWidth, 16 and 40 rem by default, and never leaves the other pane less than 16 rem.
The arrow keys move it 1 rem, 5 rem with Shift, and Page Up and Page Down 5 rem.
width and onWidthChange, which receives each width in rem and committed once a drag ends or a key moves it, as Sheet's do, let the application control it.
The divider is the gap between two surfaces: give each pane a Surface as tall as the pane, with min-block-size: 100%, and where the detail shows alone, its surface fills the room below the back button.
Panes keeps the same gap without a divider.

persist keeps the width people choose in a cookie of that name. Read it on the server with readPanesWidth(cookieHeader, key) and pass it as persistedWidth, so nothing moves as the page hydrates.

<Panes.Root
  behavior="supporting"
  defaultWidth={18}
  minWidth={14}
  maxWidth={28}
  persist="details-width"
>
  <Panes.Main label="Canvas">…</Panes.Main>
  <Panes.Divider label="Resize details" />
  <Panes.Supporting label="Canvas details">…</Panes.Supporting>
</Panes.Root>

Composition

The parts are the root, env-panes, with data-behavior, data-split-at and data-open; the main pane, env-panes-main, and the supporting one, env-panes-supporting, with its close button, env-panes-close, and its backdrop, env-panes-backdrop, while it is a sheet, and the trigger that opens it, env-panes-trigger; the list, env-panes-list, and the detail, env-panes-detail, with its back button, env-panes-back; and the divider, env-panes-divider. Panes paints no background of its own: the surfaces in its panes do. name names the node for dev mode, as data-env-name.

Accessibility

You provide

The labels and the backLabel, in the application's language.
open, and aria-current on the list's current row.
A Panes.Trigger, or a button of your own, that opens the supporting pane in less room.

envUI provides

Named regions for the panes with a label.
The supporting sheet as a modal dialog: focus moves in and stays, the rest of the page is inert, and focus returns as it closes.
Focus on the back button as the detail opens alone, and on the list's current row as it closes.
The divider as a focusable separator with its value in rem.
Panes.Trigger, which opens the supporting sheet, says whether it is open with aria-expanded, and hides while the panes sit side by side.

Props

Panes.Root

Two panes side by side, after Material's pane patterns, and how they behave in less room: a main pane with a supporting pane that becomes a sheet over it, or a list and its detail, one at a time. Invisible structure that never paints, except the supporting pane while it is a sheet, which is modal. Its own width decides, in CSS: it is the env-panes container. Each pane scrolls on its own when Panes has a height, as in a Scaffold's body that scrolls; an optional Panes.Divider resizes them.

Prop	Type	Description
`behavior`required	`'supporting''list-detail'`	supporting: Panes.Main and Panes.Supporting, such as a document and its details; below `splitAt` the supporting pane is a sheet over the main one while `open`. list-detail: Panes.List and Panes.Detail, such as messages and the one chosen; below `splitAt` one shows at a time, the detail while `open`, with a back button to the list.
`splitAt`Default `'expanded'`	`'medium''expanded''large'`	The window class of the Panes' own width from which the panes sit side by side: medium (37.5 rem), expanded (52.5 rem) or large (75 rem). Narrower, they behave as `behavior` says. CSS decides it, so the server's markup is right before any script runs.
`open`	`boolean`	Below `splitAt`: whether the supporting sheet is open, or the detail shows instead of the list, for Panes the application controls with onOpenChange, such as a list-detail that opens the detail as an item is chosen. Side by side, both panes show whatever it is.
`defaultOpen`Default `false`	`boolean`	Whether uncontrolled Panes start with the supporting sheet open, or the detail shown, below `splitAt`. Panes.Trigger opens the sheet, and Escape, the close button, the backdrop and the back button close what shows.
`onOpenChange`	`(open: boolean, details: OpenChangeDetails) => void`	Called with the new state, and why: true when Panes.Trigger opens the supporting sheet, and false when people close what `open` shows below `splitAt`: Escape, the close button or a press on the backdrop closes the supporting sheet, and the back button returns from the detail to the list.
`closeLabel`Default `'Close', or EnvUIProvider's messages.panes.close`	`string`	The name of the supporting sheet's close button, which shows only while the pane is a sheet.
`backLabel`Default `'Back', or EnvUIProvider's messages.panes.back`	`string`	The back button's label in a list-detail's detail, below `splitAt`. Name where it goes, such as All projects.
`width`	`number`	The resized pane's width in rem, for Panes the application controls with onWidthChange: the supporting pane, or the list. It applies while the panes sit side by side.
`defaultWidth`Default `22.5`	`number`	The resized pane's width in rem until people choose one with Panes.Divider, or one is kept under `persist`, and the width a double click on the divider returns it to.
`onWidthChange`	`(width: number, details: ResizeDetails) => void`	Receives each new width of the resized pane, in rem: while dragging the divider with committed false, and with committed true as a drag ends, a key moves it or a double click resets it.
`minWidth`Default `16`	`number`	The resized pane's smallest width, in rem.
`maxWidth`Default `40`	`number`	The resized pane's largest width, in rem. It never leaves the other pane less than 16 rem.
`persist`	`string`	Keeps the width people choose in a cookie of this name, for Panes the application doesn't control; a double click on the divider forgets it and returns to `defaultWidth`. Read it on the server with `readPanesWidth(cookieHeader, key)` and pass it as `persistedWidth`, so the server's markup has it and nothing moves as the page hydrates. Without that, the kept width applies after the first render.
`persistedWidth`	`number`	The width kept under `persist`, in rem, as the server read it from the request's cookies with `readPanesWidth`: the first render uses it, on the server and in the browser alike.
`name`	`string`	A name for this node, such as "inbox", which dev mode and the docs show; it renders as `data-env-name`.
`children`required	`ReactNode`	The panes: Panes.Main, an optional Panes.Divider and Panes.Supporting; or Panes.List, an optional Panes.Divider and Panes.Detail.