Titled card container for charts and data visualisations.

chart_shell/1 wraps any charting library output in a semantic PhiaUI Card, providing consistent header chrome (title, description, period label, action buttons) and a minimum-height content area — all without coupling to a specific charting library.

When to use

Use chart_shell/1 when you want the standard PhiaUI card presentation around a chart but need full control over the chart itself (custom hooks, third-party libraries, canvas elements, SVG, etc.). For a batteries-included experience, use phia_chart/1 which combines chart_shell/1 with the PhiaChart hook automatically.

Anatomy

┌──────────────────────────────────────────────────────┐
│  card_header                                         │
│  ┌──────────────────────────┐  ┌──────────────────┐ │
│  │ title                    │  │ period  | actions │ │
│  │ description (optional)   │  │                   │ │
│  └──────────────────────────┘  └──────────────────┘ │
├──────────────────────────────────────────────────────┤
│  card_content                                        │
│  ┌────────────────────────────────────────────────┐ │
│  │  chart content area (min-height: 300px)        │ │
│  └────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────┘

Basic example — custom Chart.js hook

<.chart_shell
  title="Revenue Over Time"
  description="Monthly recurring revenue"
  period="Last 12 months"
  min_height="350px"
>
  <:actions>
    <.button variant={:outline} size={:sm}>Export CSV</.button>
  </:actions>
  <canvas id="revenue-chart" phx-hook="RevenueChart" class="w-full h-full" />
</.chart_shell>

Example with ECharts (manual hook wiring)

<.chart_shell title="User Growth" period="Last 90 days" min_height="400px">
  <div
    id="growth-chart"
    phx-hook="PhiaChart"
    data-config={Jason.encode!(@chart_config)}
    data-series={Jason.encode!(@chart_series)}
    style="height: 400px"
    class="w-full"
  />
</.chart_shell>

Example with multiple action buttons

<.chart_shell
  title="Conversion Funnel"
  description="Visitors to paying customers"
  period="Q1 2026"
  min_height="300px"
>
  <:actions>
    <.button variant={:ghost} size={:sm}><.icon name="refresh-cw" /></.button>
    <.button variant={:outline} size={:sm}>Download</.button>
  </:actions>
  <canvas id="funnel-chart" phx-hook="FunnelChart" />
</.chart_shell>

Responsive min-height

The min_height attribute accepts any CSS length: "300px", "20rem", "50vh". The container enforces this minimum so that the chart area does not collapse to zero before the JS hook mounts and sizes the canvas.

Library compatibility

chart_shell/1 renders a plain <div> inside its content area. Any charting library that targets a DOM element can be used:

• ECharts via the PhiaChart hook (built-in)
• Chart.js via the PhiaChart hook fallback or a custom hook
• D3.js — mount on the container div ID
• Vega-Lite — target the inner div
• SVG charts — render inline SVG directly as inner block