@devstool/shadcn-echarts

Beautiful shadcn-style ECharts components.

@devstool/shadcn-echarts started from a personal need: getting Apache ECharts breadth with a modern, minimal shadcn/ui look without rebuilding setup from scratch.

Maintained by @noobships under the devstool brand.

Quick Links

• Official website: https://shadcn-echarts.devstool.dev
• Live demo app: https://shadcn-echarts-demo.devstool.dev/dashboard
• npm package: https://www.npmjs.com/package/@devstool/shadcn-echarts
• Demo repository: https://github.com/noobships/shadcn-echarts-demo
• Issues: https://github.com/noobships/shadcn-echarts/issues

Why This Project Exists

• shadcn-style chart components that feel native in modern dashboards
• Automatic dark/light mode behavior
• Minimal defaults that do not fight your own explicit styles
• Tree-shakeable exports to keep bundle size clean
• Multiple installation paths: npm package, shadcn registry, or manual ownership

Installation

Option 1: Install from npm (recommended)

pnpm add @devstool/shadcn-echarts echarts react

Option 2: Install a component from registry URL

npx shadcn@latest add https://shadcn-echarts.devstool.dev/r/bar-chart.json

Option 3: Install with @devstool shadcn namespace

Add this to your components.json:

{
  "registries": {
    "@devstool": "https://shadcn-echarts.devstool.dev/r/{name}.json"
  }
}

Then run:

npx shadcn@latest add @devstool/bar-chart

Option 4: Manual source ownership

Copy files from registry/default/* into your project, then modify as needed.

Quick Usage

import { BarChart } from "@devstool/shadcn-echarts";

export function MyChart() {
  return (
    <BarChart
      option={{
        xAxis: { type: "category", data: ["Mon", "Tue", "Wed"] },
        yAxis: { type: "value" },
        series: [{ type: "bar", data: [150, 230, 224] }],
      }}
      height={320}
    />
  );
}

First-load animation

Charts now animate on initial mount by default:

• animateOnMount (default true)
• animateOnMountDelayMs (default 16)

Disable if you want raw immediate rendering:

<BarChart option={option} animateOnMount={false} />

Optional: resolve color tokens in custom options

If you pass deeply customized option trees with CSS-token-like colors, you can pre-resolve them:

import { resolveOptionColorTokens } from "@devstool/shadcn-echarts/themes";

const safeOption = resolveOptionColorTokens(option);

2D vs 3D/WebGL Support

• 2D charts work out of the box with echarts.
• 3D/WebGL charts are supported, but require the echarts-gl plugin.
• Browsers already provide WebGL. You do not install WebGL directly.
• 3D support is currently early and not yet battle-tested across many real-world apps.

Enable 3D/WebGL charts

pnpm add echarts-gl

Import echarts-gl once in a client entry (for example, your app provider or client layout wrapper):

'use client'
import 'echarts-gl'

Local Development

Requirements

• Node.js 18+
• pnpm 9+

Setup

pnpm install

Core scripts

# Build library once
pnpm build

# Watch-mode library build
pnpm dev

# Type checks
pnpm type-check

# Lint
pnpm lint
pnpm lint:fix

Registry and docs site

# Build and verify shadcn registry assets
pnpm registry:build
pnpm registry:verify

# Run docs website (apps/www)
pnpm www:dev
pnpm www:build

Demo workspace

pnpm -C demo dev

Repository Layout

src/                 # Core chart components, hooks, themes, presets
registry/            # shadcn registry source files
apps/www/            # Public docs/registry website
demo/                # Standalone demo app + visual tests
docs/                # Internal docs (style, presets, theming, release)
scripts/             # Build and verification scripts

Registry Endpoints

• Index: https://shadcn-echarts.devstool.dev/registry.json
• Item format: https://shadcn-echarts.devstool.dev/r/<component>.json

Contributing

Contributions are welcome. Start here: CONTRIBUTING.md.

Issues and Feedback

Open an issue: https://github.com/noobships/shadcn-echarts/issues

License

MIT License. See LICENSE.