Docs
Charts

Charts

Composable charts for Reports, Dashboards and other visualizations.

This component uses Recharts
Loading...
'use client'
 
import {
  Chart,
  ChartCard,
  ChartContent,
  ChartHeader,
  ChartEmptyState,
  ChartLoadingState,
  ChartMetric,
} from 'ui-patterns/Chart'
import { BarChart2 } from 'lucide-react'
import { LogsBarChart } from 'ui-patterns/LogsBarChart'
import { useState, useEffect } from 'react'
 
export function ComposedChartDemo() {
  const [isLoading, setIsLoading] = useState(true)
 
  const data = Array.from({ length: 60 }, (_, i) => {
    const date = new Date()
    date.setMinutes(date.getMinutes() - i * 5) // Each point 5 minutes apart
 
    return {
      timestamp: date.toISOString(),
      ok_count: Math.floor(Math.random() * 100), // Random value 0-99
      error_count: Math.floor(Math.random() * 50), // Random value 0-50
      warning_count: Math.floor(Math.random() * 50), // Random value 0-50
    }
  }).reverse()
 
  const totalUsersValue = 4663
 
  useEffect(() => {
    setTimeout(() => {
      setIsLoading(false)
    }, 1000)
  }, [])
 
  return (
    <div className="w-8/12">
      <Chart isLoading={isLoading}>
        <ChartCard>
          <ChartHeader>
            <ChartMetric
              label="Total Users"
              value={totalUsersValue.toLocaleString('en-US')}
              tooltip="This is a tooltip"
            />
            <div className="flex items-center gap-6">
              <ChartMetric label="Warn" value="1.2k" status="warning" align="end" />
              <ChartMetric label="Err" value="736" status="negative" align="end" />
            </div>
          </ChartHeader>
          <ChartContent
            isEmpty={data.length === 0}
            emptyState={
              <ChartEmptyState
                icon={<BarChart2 size={16} />}
                title="No data to show"
                description="It may take up to 24 hours for data to refresh"
              />
            }
            loadingState={<ChartLoadingState />}
          >
            <div className="h-40">
              <LogsBarChart data={data} isFullHeight={true} />
            </div>
          </ChartContent>
        </ChartCard>
      </Chart>
    </div>
  )
}

About

Charts are an integral part of Observability at Supabase. Charts aim to be composable and reusable for frictionless setup.

Our charts use a combination of our own presentational components and Recharts for extensibility.

Best Practices

  1. Use provided chart types first: Always try to use the default provided charts first, otherwise passing Recharts compoennts to <ChartContent> is possible but not recommended to avoid complexity.

  2. Use the useChart context to show loading and disabled states: The useChart context provides boolean flags for child components to show isLoading and isDisabled states.

  3. Keep it simple: Try to avoid abstracting the chart content too much. These components should cover most of your presentational needs.

Examples

Basic Chart Types

Loading...

Chart States

Loading...

Charts as Standalone Metrics

Loading...

Charts with Actions

Loading...

Chart with Table

Loading...

You can pass through our Table component to the ChartFooter and expect it to be styled correctly. There is no additional need to style the table, ChartFooter will handle the styling for you.

API

Chart

The root container component that provides chart context to all child components.

PropTypeDefaultDescription
childrenReact.ReactNode-Chart child components
isLoadingbooleanfalseShows loading state in child components via the useChart context
isDisabledbooleanfalseDisables chart interactions via the useChart context
classNamestring-Additional CSS classes
...propsReact.HTMLAttributes<HTMLDivElement>-All standard div props

ChartCard

A card wrapper for the chart. Can be used as a Card component or as a slot.

PropTypeDefaultDescription
childrenReact.ReactNode-Chart content
asChildboolean-Render as child component (uses Slot) - ideal for removing the Card wrapper
classNamestring-Additional CSS classes
...propsReact.HTMLAttributes<HTMLDivElement>-All standard div props

ChartHeader

Container for chart header content like title and actions.

PropTypeDefaultDescription
childrenReact.ReactNode-Header content (typically ChartTitle, ChartActions, or ChartMetric)
align'start' | 'center''center'Alignment of header content
classNamestring-Additional CSS classes
...propsReact.HTMLAttributes<HTMLDivElement>-All standard div props

ChartTitle

Displays the chart title with optional tooltip.

PropTypeDefaultDescription
childrenReact.ReactNode-Title text
tooltipstring-Tooltip text shown on help icon hover
classNamestring-Additional CSS classes
...propsReact.HTMLAttributes<HTMLDivElement>-All standard div props

ChartActions

Renders action buttons or links in the chart header.

PropTypeDefaultDescription
actionsChartAction[]-Array of action objects (see ChartAction type below)
childrenReact.ReactNode-Custom action content (takes precedence over actions prop)
classNamestring-Additional CSS classes
...propsReact.HTMLAttributes<HTMLDivElement>-All standard div props

ChartAction Type

PropertyTypeDescription
labelstringAccessible label for the action
iconReact.ReactNodeIcon component to display
onClick() => voidClick handler for button actions
hrefstringURL for link actions
type'button' | 'link'Action type (auto-detected if href is provided)
classNamestringAdditional CSS classes

ChartMetric

Displays a metric value with optional status indicator.

PropTypeDefaultDescription
labelstring-Metric label text
valuestring | number | null | undefined-Metric value to display
diffValuestring | number | null | undefined-Differential value to display (shown as +/- change)
status'positive' | 'negative' | 'warning' | 'default'-Status indicator color
align'start' | 'end''start'Alignment of the metric
tooltipstring-Tooltip text shown on help icon hover
classNamestring-Additional CSS classes
...propsReact.HTMLAttributes<HTMLDivElement>-All standard div props

ChartContent

Container for the main chart visualization. Handles loading and empty states.

PropTypeDefaultDescription
childrenReact.ReactNode-Chart visualization content
isEmptybooleanfalseWhether to show empty state
emptyStateReact.ReactNode-Custom empty state component
loadingStateReact.ReactNode-Custom loading state component
disabledStateReact.ReactNode-Custom disabled state component
disabledActionsChartAction[]-Actions to show when chart is disabled
classNamestring-Additional CSS classes
...propsReact.HTMLAttributes<HTMLDivElement>-All standard div props

ChartEmptyState

Pre-built empty state component for charts.

PropTypeDefaultDescription
titlestring-Empty state title
descriptionstring-Empty state description
iconReact.ReactNode-Optional icon to display
classNamestring-Additional CSS classes
...propsReact.HTMLAttributes<HTMLDivElement>-All standard div props

ChartLoadingState

Pre-built loading state component. Takes no props.

ChartFooter

Container for footer content below the chart.

PropTypeDefaultDescription
childrenReact.ReactNode-Footer content
classNamestring-Additional CSS classes
...propsReact.HTMLAttributes<HTMLDivElement>-All standard div props

ChartConfig

Type definition for chart configuration used with Recharts components.

type ChartConfig = {
  [key: string]: {
    label?: React.ReactNode
    icon?: React.ComponentType
  } & (
    | { color?: string; theme?: never }
    | { color?: never; theme: Record<'light' | 'dark', string> }
  )
}
PropertyTypeDescription
labelReact.ReactNodeLabel for the data series
iconReact.ComponentTypeIcon component for the data series
colorstringSingle color value (mutually exclusive with theme)
themeRecord<'light' | 'dark', string>Theme-aware color values (mutually exclusive with color)

ChartLine

Line chart component for displaying time-series data.

PropTypeDefaultDescription
dataChartLineTick[]-Array of data points with timestamp
dataKeystring-Key in data object to plot
configChartConfig?-Chart configuration for styling
onLineClick(datum: ChartLineTick, tooltipData?: CategoricalChartState) => void-Click handler for line points
DateTimeFormatstring'MMM D, YYYY, hh:mma'Date format for tooltips and labels
isFullHeightbooleanfalseWhether chart should take full height
classNamestring-Additional CSS classes
colorstring'hsl(var(--brand-default))'Line color
hoverColorstring'hsl(var(--brand-500))'Line color on hover
chartHighlightChartHighlight-Highlight selection configuration
updateDateRange(from: string, to: string) => void-Callback when date range is updated via highlight
highlightActionsChartHighlightAction[]-Actions to show when area is highlighted
syncIdstring-ID to sync multiple charts
showHighlightAreabooleantrueWhether to show highlight area
cursorstring-Cursor style (defaults to 'crosshair' if chartHighlight provided)
showGridbooleanfalseWhether to show grid lines
showYAxisbooleanfalseWhether to show Y-axis
YAxisPropsobject-Additional Y-axis props (tick, tickFormatter, width, etc.)
strokeWidthnumber1.5Line stroke width

ChartLineTick Type

PropertyTypeDescription
timestampstringTimestamp for the data point
[key: string]string | numberAdditional data fields

ChartHighlight Type

PropertyTypeDescription
handleMouseDown(e: { activeLabel?: string; coordinates?: string }) => voidMouse down handler
handleMouseMove(e: { activeLabel?: string; coordinates?: string }) => voidMouse move handler
handleMouseUp(e: { chartX?: number; chartY?: number }) => voidMouse up handler
coordinates{ left?: string; right?: string }Highlight area coordinates
clearHighlight() => void?Optional function to clear highlight

ChartHighlightAction Type

PropertyTypeDescription
idstringUnique identifier for the action
labelstring | ((ctx: { start: string; end: string; clear: () => void }) => string)Action label or function that returns label
iconReactNode?Optional icon component
isDisabled(ctx: { start: string; end: string; clear: () => void }) => boolean?Optional function to determine if action is disabled
onSelect(ctx: { start: string; end: string; clear: () => void }) => voidAction selection handler

ChartBar

Bar chart component for displaying time-series data.

PropTypeDefaultDescription
dataChartBarTick[]-Array of data points with timestamp
dataKeystring-Key in data object to plot
configChartConfig?-Chart configuration for styling
onBarClick(datum: ChartBarTick, tooltipData?: CategoricalChartState) => void-Click handler for bars
DateTimeFormatstring'MMM D, YYYY, hh:mma'Date format for tooltips and labels
isFullHeightbooleanfalseWhether chart should take full height
classNamestring-Additional CSS classes
colorstring'hsl(var(--brand-default))'Bar color
hoverColorstring'hsl(var(--brand-500))'Bar color on hover
chartHighlightChartHighlight-Highlight selection configuration
updateDateRange(from: string, to: string) => void-Callback when date range is updated via highlight
highlightActionsChartHighlightAction[]-Actions to show when area is highlighted
syncIdstring-ID to sync multiple charts
showHighlightAreabooleantrueWhether to show highlight area
cursorstring-Cursor style (defaults to 'crosshair' if chartHighlight provided)
showGridbooleanfalseWhether to show grid lines
showYAxisbooleanfalseWhether to show Y-axis
YAxisPropsobject-Additional Y-axis props (tick, tickFormatter, width, etc.)

ChartBarTick Type

PropertyTypeDescription
timestampstringTimestamp for the data point
[key: string]string | numberAdditional data fields