# @dschz/solid-highcharts [](LICENSE) [](https://github.com/highcharts/highcharts) [](https://www.npmjs.com/package/@dschz/solid-highcharts) [](https://bundlephobia.com/package/@dschz/solid-highcharts) [](https://jsr.io/@dschz/solid-highcharts) [](https://github.com/dsnchz/solid-highcharts/actions/workflows/ci.yaml) [](https://discord.gg/yVBGJfTfQy) A comprehensive SolidJS wrapper for [Highcharts](https://www.highcharts.com/) that provides type-safe, reactive chart components with proper lifecycle management. ## ✨ Features - 🎯 **Type-Safe**: Full TypeScript support with proper type inference - ⚡ **Reactive**: Seamless integration with SolidJS reactivity system - 🏗️ **Modular**: Support for all Highcharts variants (Core, Stock, Maps, Gantt) - 🧹 **Clean**: Automatic cleanup and memory management - 📱 **Responsive**: Built-in responsive chart behavior - 🎨 **Customizable**: Full access to Highcharts configuration options ## ⚖️ Licensing **Important**: This wrapper library (`@dschz/solid-highcharts`) is MIT licensed, but **Highcharts itself is a commercial product** that requires a license for most use cases. ### Highcharts Licensing - 🏢 **Commercial Use**: Requires a [Highcharts license](https://shop.highcharts.com/) for commercial projects - 🎓 **Non-Commercial**: Free for personal projects, school websites, and non-profit organizations - 🧪 **Evaluation**: Free for testing and evaluation purposes ### License Requirements by Use Case | Use Case | Highcharts License Required | | -------------------------------- | --------------------------- | | Personal/hobby projects | ❌ **Free** | | Educational/school websites | ❌ **Free** | | Non-profit organizations | ❌ **Free** | | Commercial websites/applications | ✅ **License Required** | | SaaS products | ✅ **License Required** | | Products for sale | ✅ **License Required** | 📋 **Before using Highcharts in your project**, please review the [official Highcharts license terms](https://www.highcharts.com/products/highcharts/#non-commercial) to determine if you need to purchase a license. This wrapper library simply provides SolidJS integration - all Highcharts licensing terms apply to your usage of the underlying Highcharts library. ## 📦 Installation ```bash # Using npm npm install highcharts @dschz/solid-highcharts # Using yarn yarn install highcharts @dschz/solid-highcharts # Using pnpm pnpm install highcharts @dschz/solid-highcharts # Using bun bun install highcharts @dschz/solid-highcharts ``` ### Highcharts Module Usage All Highcharts functionality is available from the single `highcharts` package via different import paths. **⚠️ Important: Import order matters!** Highcharts modules must be imported after the core module. **📦 Highcharts v12+**: As of Highcharts version 12, you should use ESM import paths for better compatibility and tree-shaking. The examples below show the recommended ESM imports. ```tsx // Core Highcharts (standard charts) - ESM import import Highcharts from "highcharts/esm/highcharts"; // Stock Charts (financial/time-series data) - ESM import import HighchartsStock from "highcharts/esm/highstock"; // Maps (geographical data) - ESM import import HighchartsMaps from "highcharts/esm/highmaps"; // Gantt Charts (project timelines) - ESM import import HighchartsGantt from "highcharts/esm/highcharts-gantt"; // Additional modules (optional) -- ORDER MATTERS! MUST BE IMPORTED AFTER Highcharts IMPORT! import "highcharts/esm/modules/accessibility"; import "highcharts/esm/modules/exporting"; import "highcharts/esm/modules/export-data"; ``` See this [post](https://www.highcharts.com/docs/getting-started/version-12) for more details. **Legacy UMD imports** (pre-v12) are still supported but ESM is recommended: ```tsx // Legacy UMD imports (still works but not recommended) import Highcharts from "highcharts"; import HighchartsStock from "highcharts/highstock"; import HighchartsMaps from "highcharts/highmaps"; import HighchartsGantt from "highcharts/highcharts-gantt"; // Additional modules (optional) -- ORDER MATTERS! MUST BE IMPORTED AFTER Highcharts IMPORT! import "highcharts/modules/accessibility"; import "highcharts/modules/exporting"; import "highcharts/modules/export-data"; ``` ### API Quick Start This library exposes four factory functions that create the Highcharts components to use in your Solid application. #### Basic Chart ```tsx import Highcharts from "highcharts/esm/highcharts"; import { createChart } from "@dschz/solid-highcharts"; // Highcharts Chart component const Chart = createChart(Highcharts); ``` #### Stock Chart ```tsx // To create a StockChart import Highcharts from "highcharts/esm/highstock"; import { createStockChart } from "@dschz/solid-highcharts"; // Highcharts StockChart component const StockChart = createStockChart(Highcharts); ``` #### Map Chart ```tsx // To create a MapChart import Highcharts from "highcharts/esm/highmaps"; import { createMapChart } from "@dschz/solid-highcharts"; // Highcharts MapChart component const MapChart = createMapChart(Highcharts); ``` #### Gantt Chart ```tsx // To create a GanttChart import Highcharts from "highcharts/esm/highcharts-gantt"; import { createGanttChart } from "@dschz/solid-highcharts"; // Highcharts GanttChart component const GanttChart = createGanttChart(Highcharts); ``` #### Accessibility / Exporting Modules For additional modules like `exporting` and `accessibility`, you simply import them to register with Highcharts: ```tsx import Highcharts from "highcharts/esm/highcharts"; import "highcharts/esm/modules/accessibility"; import "highcharts/esm/modules/exporting"; import "highcharts/esm/modules/export-data"; import { createChart } from "@dschz/solid-highcharts"; const Chart = createChart(Highcharts); ``` **Note**: You may need to disable import sorting rules (like `simple-import-sort` or Prettier) for these imports to prevent automatic reordering that would break functionality as the additional modules must be imported **AFTER** the target Highcharts module import. ## 🔧 Component Props All chart components returned from the factory functions accept the same props interface: ```tsx type HighchartOptions = Highcharts.Options & { animation?: boolean | Partial; }; type HighchartsComponentProps = HighchartOptions & { /** CSS class for container */ class?: string; /** CSS styles for container */ style?: JSX.CSSProperties; /** Access to container element */ ref?: (container: HTMLDivElement) => void; /** Callback when chart is created */ onCreateChart?: (chart: Highcharts.Chart) => void; }; ``` ### Props Examples ```tsx // Basic styling // Chart reference and callbacks console.log('Container:', container)} onCreateChart={(chart) => { // Access chart instance chart.setTitle({ text: 'Updated Title' }); // Add custom event listeners chart.container.addEventListener('click', () => { console.log('Chart clicked!'); }); }} series={[{ type: 'line', data: [1, 2, 3] }]} /> ``` ## 🎨 Styling and Theming ### CSS Styling All charts have a default `solid-highcharts` class that you can use for global styling: ```css /* Global chart styles */ .solid-highcharts { border-radius: 8px; box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1); background: #ffffff; } /* Dark mode support */ .dark .solid-highcharts { background: #1a1a1a; border-color: #333; } /* Custom chart class */ .my-chart { background: #f5f5f5; padding: 16px; } /* Responsive behavior */ .chart-responsive { width: 100%; height: 400px; min-height: 300px; } @media (max-width: 768px) { .chart-responsive { height: 300px; } } ``` You can combine the base class with your custom classes: ```tsx ``` ### Highcharts Theming ```tsx import Highcharts from "highcharts/esm/highcharts"; import { createChart } from "@dschz/solid-highcharts"; // Apply global theme Highcharts.setOptions({ colors: ["#058DC7", "#50B432", "#ED561B", "#DDDF00"], chart: { backgroundColor: "#f9f9f9", style: { fontFamily: "Inter, sans-serif", }, }, title: { style: { color: "#333", fontSize: "18px", }, }, }); const Chart = createChart(Highcharts); ``` ### Framework Integration The base class works well with CSS frameworks: ```css /* Tailwind-like utilities */ .solid-highcharts { @apply rounded-lg shadow-md bg-white dark:bg-gray-800; } /* CSS Modules */ .chart { composes: solid-highcharts; /* Additional styles */ } ``` ## 📈 Performance Tips ### 1. Use Chart Boost for Large Datasets ```tsx import Highcharts from "highcharts/esm/highcharts"; import "highcharts/esm/modules/boost"; ; ``` ## 🤝 Contributing All contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details. ### Development Setup ```bash # Clone the repository git clone https://github.com/dsnchz/solid-highcharts.git cd solid-highcharts # Install dependencies bun install # Run tests bun test # Build the library bun run build # Start development server bun start ``` ## 📄 License MIT © [Daniel Sanchez](https://github.com/dsnchz)