Widget

A Widget is a container that structures content behind a titled header with its own actions, most often on a dashboard.

Import#

import { Widget } from '@volue/wave-react';

Widget is a compound component made up of several parts:

Widget.Root: The wrapper that contains all the parts of a widget.
Widget.Header: The header strip holding the title and the actions.
Widget.Title: The title. Renders an h3 by default.
Widget.Subtitle: Optional supporting text below the title.
Widget.Actions: The container for header actions. Moves actions that no longer fit into an overflow popover.
Widget.Select: An action that opens a selection.
Widget.SelectClear: A button beside a select that clears or resets its selection.
Widget.Button: A labelled action.
Widget.IconButton: A square, icon-only action.
Widget.Body: The wrapper containing the widget's main content.

When to use#

Widgets encapsulate a feature that stands on its own, in a styled container with a title and controls of its own. Dashboard panels are the typical case. They are responsive: as a widget narrows, its header collapses the actions into an overflow popover. A Card belongs a level below: it groups related content, even inside a widget itself.

Examples#

Basic#

Every widget is exposed to assistive technology as a region landmark named by its title, so screen reader users can jump between the widgets of a dashboard.

Visual variants#

The variant prop picks how the widget separates from its surroundings, either outlined by a border or lifted by an elevation.

With a subtitle#

Add Widget.Subtitle alongside Widget.Title, and the header stacks them for you.

Sizes#

Widget comes in medium and small sizes.

Vertical scroll#

Widget.Body scrolls on its own within whatever height the surrounding layout gives the widget.

Clearable select#

Put a Widget.SelectClear in a select's endElement slot to let users clear it in one click. The button shows only while the select has a value.

Actions#

Widget.Actions holds the header's controls. There are three kinds of action:

Widget.Select is a labelled action that shows the current value. Use it for choosing something.
Widget.Button is a labelled action, usually with a leftIcon.
Widget.IconButton is an icon-only action.

None of them has any behaviour of its own. Each one is a trigger, and you choose what it opens. Compose an action with a SingleSelectMenu.CustomTrigger, a Combobox.CustomTrigger, a Popover.Trigger, a Dialog.Trigger or any other trigger component, and the action becomes that trigger.

<SingleSelectMenu.Root value={period} onValueChange={setPeriod}>
  <SingleSelectMenu.CustomTrigger
    as={Widget.Select}
    label="Period"
    value={period}
  />
  <SingleSelectMenu.Content>{/* the choices */}</SingleSelectMenu.Content>
</SingleSelectMenu.Root>

Widget.Actions is responsive. When the actions no longer fit the widget's width, the leading ones move into an overflow popover and stack there as outline Buttons. Collapsing changes nothing about what an action does. It still opens the same menu, popover or dialog as it did in the header.

Drag the preview's edge to watch the actions collapse one by one, and open one from the overflow popover to see it still working as the same trigger.

In this example the body sets padding="none" so the Table runs flush to the widget's edges. Do the same for charts and other edge-to-edge content.

See complete example in Storybook

API reference#

Widget.Root#

Prop	Type	Default
`as`	`enum`	`div`
`css`	`StitchesCss`	No default value
`variant`	`enum`	`"bordered"`
`size`	`enum`	`"medium"`

Widget.Header#

Prop	Type	Default
`as`	`enum`	`div`
`css`	`StitchesCss`	No default value

Widget.Title#

Prop	Type	Default
`as`	`enum`	`h3`
`css`	`StitchesCss`	No default value

Widget.Subtitle#

Prop	Type	Default
`as`	`enum`	`span`
`css`	`StitchesCss`	No default value

Widget.Actions#

Prop	Type	Default
`overflowLabel`	`string`	`"More actions"`
`css`	`StitchesCss`	No default value

Widget.Select#

Prop	Type	Default
`as`	`enum`	`button`
`css`	`StitchesCss`	No default value
`label`	`React.ReactNode`	No default value
`value`	`React.ReactNode`	No default value
`placeholder`	`React.ReactNode`	No default value
`endElement`	`React.ReactElement`	No default value
`isActive`	`boolean`	`false`
`isDisabled`	`boolean`	`false`

Widget.SelectClear#

Prop	Type	Default
`css`	`StitchesCss`	No default value
`label`	`string`	`"Clear"`
`onClick`*	`function`	No default value

Widget.Button#

Prop	Type	Default
`as`	`enum`	`button`
`css`	`StitchesCss`	No default value
`leftIcon`	`React.ReactElement`	No default value
`isActive`	`boolean`	`false`
`isDisabled`	`boolean`	`false`

Widget.IconButton#

Prop	Type	Default
`as`	`enum`	`button`
`css`	`StitchesCss`	No default value
`aria-label`*	`string`	No default value
`isActive`	`boolean`	`false`
`isDisabled`	`boolean`	`false`

Widget.Body#

In addition to the props below, you can pass the padding Box props to control the spacing.

Prop	Type	Default
`as`	`enum`	`div`
`css`	`StitchesCss`	No default value