Widget

A dashboard container that pairs an optional header and footer with an elevated content card for charts, tables, and KPIs.

Import

import { Widget } from 'heroui-native-pro';

Anatomy

<Widget>
  <Widget.Header>
    <Widget.Title>...</Widget.Title>
    <Widget.Description>...</Widget.Description>
    <Widget.Legend>
      <Widget.LegendItem>...</Widget.LegendItem>
    </Widget.Legend>
  </Widget.Header>
  <Widget.Content>...</Widget.Content>
  <Widget.Footer>...</Widget.Footer>
</Widget>
  • Widget: Root container. Renders the outer surface (bg-surface-secondary, rounded-2xl) with internal padding, and cascades disable-all to animated descendants. Sub-components are fully optional.
  • Widget.Header: Horizontal row with space-between justification. Pairs Widget.Title (and optional Widget.Description) with an inline Widget.Legend.
  • Widget.Title: Primary widget label rendered with accessibilityRole="header".
  • Widget.Description: Secondary muted text. Use under the title as a hint or inside Widget.Footer as a summary line.
  • Widget.Content: Elevated inner card (bg-surface, rounded-xl, shadow-surface) hosting the widget's payload (chart, table, KPI block, etc.).
  • Widget.Footer: Optional bottom row for muted summary text or action chips.
  • Widget.Legend: Inline container for one or more Widget.LegendItems, typically placed inside the header next to the title.
  • Widget.LegendItem: Single colored-dot + label entry. Accepts colorClassName (preferred) or color (inline color string) to drive the dot.

Usage

Basic usage

Compose the widget with a header (title + legend) and an elevated content card.

<Widget>
  <Widget.Header>
    <Widget.Title>Tokens Over Time</Widget.Title>
    <Widget.Legend>
      <Widget.LegendItem colorClassName="bg-chart-4">Input</Widget.LegendItem>
      <Widget.LegendItem colorClassName="bg-chart-1">Output</Widget.LegendItem>
    </Widget.Legend>
  </Widget.Header>
  <Widget.Content>...</Widget.Content>
</Widget>

Title and description

Stack a Widget.Description beneath the title for a hint line.

<Widget>
  <Widget.Header>
    <View>
      <Widget.Title>Requests</Widget.Title>
      <Widget.Description>Last 30 days</Widget.Description>
    </View>
  </Widget.Header>
  <Widget.Content>...</Widget.Content>
</Widget>

Add a Widget.Footer for muted summary text or actions below the content card.

<Widget>
  <Widget.Header>
    <Widget.Title>Tokens Over Time</Widget.Title>
  </Widget.Header>
  <Widget.Content>...</Widget.Content>
  <Widget.Footer>
    <Widget.Description>Updated 2 minutes ago</Widget.Description>
  </Widget.Footer>
</Widget>

Legend with theme colors

Use colorClassName to pull theme tokens through the standard className pipeline.

<Widget.Legend>
  <Widget.LegendItem colorClassName="bg-chart-3">Organic</Widget.LegendItem>
  <Widget.LegendItem colorClassName="bg-chart-1">Paid Ads</Widget.LegendItem>
</Widget.Legend>

Legend with custom colors

Use color for one-off color strings (hex, rgb(...), resolved theme value).

<Widget.Legend>
  <Widget.LegendItem color="#10b981">Success</Widget.LegendItem>
  <Widget.LegendItem color="#ef4444">Errors</Widget.LegendItem>
</Widget.Legend>

Example

import { LineChart, Widget } from 'heroui-native-pro';
import { View } from 'react-native';

const TOKENS_DATA = [
  { date: '09-01', input: 35000, output: 22000 },
  { date: '09-02', input: 80000, output: 35000 },
  { date: '09-03', input: 130000, output: 48000 },
];

const formatCompactNumber = (value: number) =>
  value >= 1000 ? `${(value / 1000).toFixed(0)}k` : `${value}`;

export default function WidgetExample() {
  return (
    <View className="px-5">
      <Widget>
        <Widget.Header>
          <Widget.Title>Tokens Over Time</Widget.Title>
          <Widget.Legend>
            <Widget.LegendItem colorClassName="bg-chart-4">
              Input
            </Widget.LegendItem>
            <Widget.LegendItem colorClassName="bg-chart-1">
              Output
            </Widget.LegendItem>
          </Widget.Legend>
        </Widget.Header>
        <Widget.Content>
          <LineChart
            data={TOKENS_DATA}
            xKey="date"
            yKeys={['input', 'output']}
            yAxis={[{ formatYLabel: formatCompactNumber }]}
            wrapperClassName="h-[200px]"
          >
            {({ points }) => (
              <>
                <LineChart.Line
                  points={points.input}
                  colorClassName="accent-chart-4"
                  curveType="monotoneX"
                />
                <LineChart.Line
                  points={points.output}
                  colorClassName="accent-chart-1"
                  curveType="monotoneX"
                />
              </>
            )}
          </LineChart>
        </Widget.Content>
      </Widget>
    </View>
  );
}

API Reference

Widget

proptypedefaultdescription
childrenReact.ReactNode-Compound parts to render inside the widget shell
classNamestring-Additional CSS classes for the outer shell
animationWidgetRootAnimation-Animation configuration for the widget root (cascades to animated descendants)
...ViewPropsViewProps-All standard React Native View props are supported

WidgetRootAnimation

Animation configuration for the Widget root. Can be:

  • "disable-all": Disable all animations including children (cascades down through AnimationSettingsProvider)
  • undefined: Use default animations

Widget.Header

proptypedefaultdescription
childrenReact.ReactNode-Header content (title, description, legend, etc.)
classNamestring-Additional CSS classes for the header row
...ViewPropsViewProps-All standard React Native View props are supported

Widget.Title

proptypedefaultdescription
childrenReact.ReactNode-Title text content
classNamestring-Additional CSS classes for the title text
...TextPropsTextProps-All standard React Native Text props are supported

Widget.Description

proptypedefaultdescription
childrenReact.ReactNode-Description text content
classNamestring-Additional CSS classes for the description text
...TextPropsTextProps-All standard React Native Text props are supported

Widget.Content

proptypedefaultdescription
childrenReact.ReactNode-Content rendered inside the elevated card
classNamestring-Additional CSS classes for the content card
...ViewPropsViewProps-All standard React Native View props are supported

Widget.Footer

proptypedefaultdescription
childrenReact.ReactNode-Footer content
classNamestring-Additional CSS classes for the footer row
...ViewPropsViewProps-All standard React Native View props are supported

Widget.Legend

proptypedefaultdescription
childrenReact.ReactNode-Legend entries
classNamestring-Additional CSS classes for the legend wrapper
...ViewPropsViewProps-All standard React Native View props are supported

Widget.LegendItem

proptypedefaultdescription
childrenReact.ReactNode-Label text. String/number children are wrapped in a Text automatically
colorstring-Color applied to the dot via inline backgroundColor. Wins over colorClassName when both are set
colorClassNamestring-Tailwind background class for the dot (e.g. "bg-chart-3"). Preferred over color for theme tokens
classNamestring-Additional CSS classes for the wrapper slot
classNamesElementSlots<WidgetLegendItemSlots>-Additional CSS classes for individual slots
stylesWidgetLegendItemStyles-Inline style overrides for individual slots
textPropsTextProps-Additional props forwarded to the inner label Text element
...ViewPropsViewProps-All standard React Native View props are supported

ElementSlots<WidgetLegendItemSlots>

slotdescription
wrapperOuter flex row holding the dot and label
dotColor indicator dot
labelLegend entry label text

styles

slottypedescription
wrapperViewStyleStyle for the outer flex row wrapper
dotViewStyleStyle for the color indicator dot
labelTextStyleStyle for the legend entry label text

On this page