{ "markdown": "
\n\n\"microcharts\n\n# @microcharts/react\n\n**Word-sized charts for React** — zero runtime dependencies, ~2–7 kB interactive · ~1–4 kB static, accessible\nby default, and server-component safe.\n\n
\n\n[![npm](https://img.shields.io/npm/v/@microcharts/react?color=2f52d4&label=npm)](https://www.npmjs.com/package/@microcharts/react)\n[![gzip per chart](https://img.shields.io/badge/per_chart-~2–7_live_·_~1–4_static_kB-2f52d4)](https://microcharts.dev/docs/performance)\n[![zero dependencies](https://img.shields.io/badge/dependencies-0-077353)](https://microcharts.dev)\n[![types](https://img.shields.io/npm/types/@microcharts/react?color=2f52d4)](https://microcharts.dev)\n[![React 18 · 19](https://img.shields.io/badge/React-18_·_19-077353)](https://microcharts.dev/docs/quickstart)\n[![MIT](https://img.shields.io/npm/l/@microcharts/react?color=666)](./LICENSE)\n[![Reviewed with Argos](https://argos-ci.com/badge.svg)](https://argos-ci.com?utm_source=ganapativs/microcharts&utm_campaign=oss)\n\n**[Docs](https://microcharts.dev)** · **[Gallery](https://microcharts.dev/docs/charts)** ·\n**[Quickstart](https://microcharts.dev/docs/quickstart)** · **[AI usage](https://microcharts.dev/docs/ai)** ·\n**[llms.txt](https://microcharts.dev/llms.txt)**\n\n
\n\n---\n\nmicrocharts is **106 tiny, handcrafted chart types** built to sit _inside_ an interface: a sentence, a table cell, a KPI\ncard, a tab header, a streamed AI reply. The grammar is small enough for a model to emit correctly mid-sentence, and\nevery chart describes itself in words, so a chart an LLM streams into a chat reply is one a person can read and check.\n\n> **Status:** tested and in production use, but not across every stack and edge yet. If you hit something, open an issue\n> on [GitHub](https://github.com/ganapativs/microcharts/issues).\n\n## Why\n\n- **AI-native.** A chart is plain `data` plus a generated sentence. One grammar across all 106 types — a model that has\n seen one chart can write them all. → [AI usage](https://microcharts.dev/docs/ai)\n- **Zero dependencies.** No chart engine, no D3 — just SVG. React is the only peer. CI-enforced, forever.\n- **Server-component safe.** Static charts are hook-free and render to HTML with **zero client JavaScript**.\n Interactivity is a separate opt-in `/interactive` import.\n- **Accessible by default.** Every chart is an `img` with a natural-language summary built from your data; it updates\n when the numbers do. → [Accessibility](https://microcharts.dev/docs/accessibility)\n- **Tiny.** **~2–7 kB interactive · ~1–4 kB static** gzip per chart, budget-gated in CI. Every type has one documented,\n honest encoding channel and a stated precision.\n- **Motion, opt-in.** Interactive charts draw on with `animate` plus one `import \"@microcharts/react/motion\"`, and glide\n continuous marks when data updates. Entrances respect `prefers-reduced-motion` and never replay over server-rendered\n HTML. → [Motion](https://microcharts.dev/docs/motion)\n\n## Install\n\n```bash\nnpm install @microcharts/react\n```\n\nImport the stylesheet **once** at the root of your app — it carries every theming token and chart style in a\nlow-specificity cascade layer, so your own styles always win:\n\n```tsx\n// app/layout.tsx\nimport \"@microcharts/react/styles.css\";\n```\n\n## Your first chart\n\nEvery chart renders from `data` alone. This works in a **React Server Component** with zero client JavaScript — pure\nSVG, and its accessible name is generated from the data.\n\n```tsx\nimport { Sparkline } from \"@microcharts/react/sparkline\";\n\n;\n```\n\nEach chart imports from its **own subpath**, so you only ship what you use. Every chart follows the same two-entry\npattern: a static default, and an `/interactive` twin.\n\n## Add interactivity\n\nNeed hover, keyboard navigation, touch, or live announcements? Import the same chart from `/interactive`. The rendered\noutput and the accessible name are identical, because the interactive entry composes its static twin. It only **adds**\nprops; you opt into the client component where it matters.\n\n```tsx\nimport { Sparkline } from \"@microcharts/react/sparkline/interactive\";\n\n;\n```\n\nEvery interactive chart shares one contract, so you learn it once. Hover or arrow keys make a unit **active**; a click,\ntap, Enter, or Space **selects** it and pins the readout so it survives blur; Escape or\na press outside the chart clears; Home/End jump to the ends. Read it back with `onActive` and\n`onSelect` — payload `{ index, value, label?, formatted? }`, where `value` is the raw number and `formatted` is the\nchart's ready-to-display string — and control the pin with `selectedIndex` / `defaultSelectedIndex`. Set\n`readout={false}` to hide the in-chart value chip and render `datum.formatted` wherever you like. Single-unit scalar\ncharts (Delta, Progress, StatusDot, Bullet, …) take `onSelect` alone.\n\n```tsx\n setHovered(d?.value ?? null)} onSelect={(d) => pin(d)} />\n```\n\n## Annotate with children\n\nThresholds, markers, and target zones are **children** — the same grammar on every chart that supports them:\n\n```tsx\nimport { Sparkline } from \"@microcharts/react/sparkline\";\nimport { Threshold, Marker } from \"@microcharts/react/annotations\";\n\n\n \n \n;\n```\n\n## Theme it\n\nAbout two dozen `--mc-*` CSS custom properties are the runtime contract; presets are token bundles. Set one on a subtree\nwith the provider — presets are visual only and never change what the data means:\n\n```tsx\nimport { MicroProvider } from \"@microcharts/react\";\n\n\n \n;\n```\n\nPresets: `modern` (default), `editorial`, `mono`, `vivid`, plus output-context `print` and `eink`. Dark mode is\nhand-tuned, not inverted. For a whole brand theme, `defineTheme` (from `@microcharts/react/theme`) derives a matched,\ncolor-blind-safe palette and dark twins from one accent:\n\n```tsx\nimport { defineTheme } from \"@microcharts/react/theme\";\n\nconst brand = defineTheme({ accent: \"#6d28d9\" });\n…;\n```\n\nRetune density with one scalar (`--mc-density`), give figures their own face (`--mc-font-numeric`), or recolor a single\ncategorical chart with a `colors` array. → [Theming guide](https://microcharts.dev/docs/theming)\n\n## The catalog\n\n**106 stable chart types** — 34 core, 26 decision, 23 expressive, 23 frontier — grouped by the _question_ each one\nanswers. `data` alone always renders something correct, and a prop name means the same thing on every chart (`domain`,\n`color`, `title`, `summary`, `label`, `format`…), so picking a chart is picking the question you need answered.\n\nSparklines, bars, deltas, and bullets through bump charts, funnels, honeycombs, calendar strips, and confidence bands —\n**[browse them all in the live gallery →](https://microcharts.dev/docs/charts)**\n\n> **Not shipping, on purpose:** pie, needle-gauge/speedometer, battery, waffle, violin. Each fails at micro scale or on\n> the honest-encoding bar, and each has an in-catalog replacement (Bullet for gauges, SegmentedBar for pie, MicroBox for\n> violin). → [what to use instead](https://microcharts.dev/llms.txt)\n\n## Made for models\n\nA model writes the chart; a person reads it. The docs site publishes machine surfaces alongside the human ones:\n\n| Surface | What it is |\n| --------------------------------------------------------- | --------------------------------------------------- |\n| [`/llms.txt`](https://microcharts.dev/llms.txt) | Curated map of the catalog and guides |\n| [`/llms-full.txt`](https://microcharts.dev/llms-full.txt) | The complete generated docs corpus |\n| [`/catalog.json`](https://microcharts.dev/catalog.json) | Every chart's name, import path, props, data shapes |\n\n## The MCP server\n\nThe surfaces above are for reading. [`@microcharts/mcp`](https://www.npmjs.com/package/@microcharts/mcp) lets an\nassistant call the library directly: a Model Context Protocol server that runs on your machine over stdio, with three\ntools backed by this library — **find** the chart type that answers a question, **get** its exact props and a\nready-to-render sample, and **render** it to a self-contained SVG with the generated alt text attached.\n\n```json\n{\n \"mcpServers\": {\n \"microcharts\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@microcharts/mcp\"]\n }\n }\n}\n```\n\nWorks in Claude Desktop, Claude Code, Cursor, and VS Code; nothing is hosted and no key is involved. The same three\ncapabilities ship as Vercel AI SDK tools on the `@microcharts/mcp/ai-sdk` subpath. Full reference:\n[microcharts.dev/docs/mcp](https://microcharts.dev/docs/mcp). Also listed in the\n[Glama MCP registry](https://glama.ai/mcp/servers/ganapativs/microcharts).\n\n## Compatibility\n\nReact **18 and 19**. ESM-only, per-component subpath exports, types-first export conditions. Static charts render in any\nRSC or SSR setup with no client runtime.\n\n`sideEffects` is a two-entry allowlist, never `false`: `styles.css` and the opt-in `./motion` engine are both imported\nfor their side effects, and `false` would let a bundler drop them. Every other module is side-effect free and\ntree-shakes normally, and since charts ship as per-component subpaths, you only pay for the ones you import.\n\n## Contributing\n\n```bash\npnpm install\npnpm check # typecheck + lint + format + test + knip\npnpm size # gzip budgets (needs a build first)\npnpm build\n```\n\nBug fixes and fixes to existing charts are the most useful thing to send. New props and new chart types are open but\nheld to a high bar — the catalog is already broad at 106 types, so a new one needs a question the others can't answer.\nEither way, open an issue and wait for a yes before you open a PR. [CONTRIBUTING.md](./CONTRIBUTING.md) has the policy,\nthe CI gates, and what a good bug report contains.\n\n## License\n\n[MIT](./LICENSE) © [Ganapati V S](https://meetguns.com)\n", "bytes": 10540, "sha": "98f976885a116bd294b9e1d776040a0c0b82e3cc1f8cd0e97824d914e36f39e7", "repo_slug": "ganapativs/microcharts", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_ganapativs_microcharts_a95a64a2/readme" }