echarts-themes

ECharts themes ESM pack with TypeScript support.

Install

npm install echarts-themes

yarn add echarts-themes

pnpm add echarts-themes

Features

• Built-in TypeScript API for official ECharts themes
• Includes all themes from apache/echarts-theme-builder
• Metadata for each theme, including name, title, and darkMode

Quick Start

import { registerTheme, use } from 'echarts/core'
import { BarChart } from 'echarts/charts'
import { GridComponent, TooltipComponent } from 'echarts/components'
import { CanvasRenderer } from 'echarts/renderers'
import {
  getThemeBundle,
  getTheme,
  getThemeMeta,
  listThemeNames,
  findThemes,
} from 'echarts-themes'

use([CanvasRenderer, BarChart, GridComponent, TooltipComponent])

const names = listThemeNames()
const dark = getTheme('dark')
const darkMeta = getThemeMeta('dark')
const darkBundle = getThemeBundle('dark')

registerTheme(darkMeta.name, dark)
registerTheme(darkBundle.meta.name, darkBundle.theme)

const darkModeThemes = findThemes({ darkMode: true })

API

• listThemeNames()
• listThemeBundles()
• listThemeMetas()
• getTheme(name)
• getThemeMeta(name)
• getThemeBundle(name)
• hasTheme(name)
• findThemes(query)

Also exports per-theme constants such as themeDark, themeDefault, themeV5, etc.

API Reference

Methods

listThemeNames(): readonly ThemeName[]

Returns all built-in theme names.

• Return type: readonly ThemeName[]
• Default behavior: no arguments, returns the full list
• Runtime behavior: each call returns a new array view

listThemeBundles(): readonly ThemeBundle[]

Returns all built-in theme bundles.

• Return type: readonly ThemeBundle[]
• Default behavior: no arguments, returns the full list
• Runtime behavior: each call returns a new array view; bundle objects are immutable

listThemeMetas(): readonly ThemeMeta[]

Returns metadata of all built-in themes.

• Return type: readonly ThemeMeta[]
• Default behavior: no arguments, returns the full list
• Runtime behavior: each call returns a new array view; metadata objects are immutable

hasTheme(name: string): name is ThemeName

Checks whether a string is a valid built-in theme name.

• Parameters:
  • name: string theme name candidate
• Return type: boolean (type guard)

getTheme(name: ThemeName): ThemeObject

Returns an ECharts theme object by name.

• Parameters:
  • name: ThemeName built-in theme name
• Return type: ThemeObject
• Runtime behavior: returned object is immutable

getThemeMeta(name: ThemeName): ThemeMeta

Returns metadata by theme name.

• Parameters:
  • name: ThemeName built-in theme name
• Return type: ThemeMeta

getThemeBundle(name: ThemeName): ThemeBundle

Returns full theme bundle by name.

• Parameters:
  • name: ThemeName built-in theme name
• Return type: ThemeBundle

findThemes(query: ThemeQuery): readonly ThemeBundle[]

Filters themes by metadata.

• Parameters:
  • query.darkMode?: boolean
    • default: undefined (disabled)
    • behavior: when set, filters by dark-mode flag
  • query.names?: readonly string[]
    • default: undefined (disabled)
    • behavior: case-insensitive match after trim() and toLowerCase()
    • whitespace-only entries are ignored
• Return type: readonly ThemeBundle[]

Exported Types

ThemeName

Union-like compile-time type derived from built-in theme names.

ThemeObject

Record<string, unknown> theme payload for echarts.registerTheme.

ThemeColor

Color string type, typically CSS-compatible values like hex/rgb/rgba.

OfficialThemeFile

Raw source JSON shape:

• version: number | string
• themeName: string
• theme: ThemeObject

ThemeMeta

Enriched metadata shape:

• name: string
• title: string
• source: 'apache/echarts-theme-builder'
• darkMode: boolean (default false when no usable background color)
• backgroundColor?: ThemeColor
• colorPalette?: ThemeColor[]

ThemeBundle

Theme package shape:

• meta: ThemeMeta
• theme: ThemeObject
• raw: OfficialThemeFile

ThemeQuery

Query parameters for findThemes:

• darkMode?: boolean
• names?: readonly string[]

Included Official Themes

chalk, dark, default, essos, halloween, infographic, macarons, purple-passion, roma, shine, v5, vintage, walden, westeros, wonderland

License

MIT License © 2025-PRESENT ntnyq