or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-charts.mdbasic-charts.mdconfiguration.mdindex.mdspecialty-charts.mdstatistical-charts.mdtiny-charts.mdutilities.md
tile.json

configuration.mddocs/

Configuration System

Global configuration system for setting defaults across all chart types using React context and configuration providers.

Capabilities

Configuration Provider

Provides global configuration context for all chart components, enabling consistent theming and default settings.

/**
 * Configuration provider component for global chart settings
 */
const ConfigProvider: ForwardRefExoticComponent<PropsWithoutRef<ConfigProviderProps> & RefAttributes<any>>;

interface ConfigProviderProps extends ConfigValue {
  /** React children components */
  children?: ReactNode;
}

interface ConfigValue {
  /** Common configuration applied to all charts */
  common?: CommonConfig;
  /** Area chart specific configuration */
  area?: AreaConfig;
  /** Bar chart specific configuration */
  bar?: BarConfig;
  /** Bidirectional bar chart specific configuration */
  bidirectionalBar?: BidirectionalBarConfig;
  /** Box plot specific configuration */
  box?: BoxConfig;
  /** Bullet chart specific configuration */
  bullet?: BulletConfig;
  /** Circle packing specific configuration */
  circlePacking?: CirclePackingConfig;
  /** Column chart specific configuration */
  column?: ColumnConfig;
  /** Dual axes chart specific configuration */
  dualAxes?: DualAxesConfig;
  /** Funnel chart specific configuration */
  funnel?: FunnelConfig;
  /** Gauge chart specific configuration */
  gauge?: GaugeConfig;
  /** Heatmap specific configuration */
  heatmap?: HeatmapConfig;
  /** Histogram specific configuration */
  histogram?: HistogramConfig;
  /** Line chart specific configuration */
  line?: LineConfig;
  /** Liquid chart specific configuration */
  liquid?: LiquidConfig;
  /** Mix chart specific configuration */
  mix?: MixConfig;
  /** Pie chart specific configuration */
  pie?: PieConfig;
  /** Radar chart specific configuration */
  radar?: RadarConfig;
  /** Radial bar chart specific configuration */
  radialBar?: CommonConfig<RadialBarOptions>;
  /** Rose chart specific configuration */
  rose?: RoseConfig;
  /** Sankey diagram specific configuration */
  sankey?: SankeyConfig;
  /** Scatter plot specific configuration */
  scatter?: ScatterConfig;
  /** Stock chart specific configuration */
  stock?: StockConfig;
  /** Sunburst chart specific configuration */
  sunburst?: SunburstConfig;
  /** Tiny area chart specific configuration */
  tinyArea?: TinyAreaConfig;
  /** Tiny column chart specific configuration */
  tinyColumn?: TinyColumnConfig;
  /** Tiny line chart specific configuration */
  tinyLine?: TinyLineConfig;
  /** Tiny progress chart specific configuration */
  tinyProgress?: TinyProgressConfig;
  /** Tiny ring chart specific configuration */
  tinyRing?: CommonConfig<TinyRingOptions>;
  /** Treemap specific configuration */
  treemap?: TreemapConfig;
  /** Venn diagram specific configuration */
  venn?: VennConfig;
  /** Violin plot specific configuration */
  violin?: ViolinConfig;
  /** Waterfall chart specific configuration */
  waterfall?: WaterfallConfig;
  /** Word cloud specific configuration */
  wordCloud?: WordCloudConfig;
}

Usage Example:

import React from "react";
import { ConfigProvider, Line, Column } from "@ant-design/plots";

const App: React.FC = () => {
  const config = {
    common: {
      theme: 'dark',
      tooltip: {
        showTitle: true,
        showMarkers: true,
      },
    },
    line: {
      smooth: true,
      point: {
        size: 3,
        shape: 'circle',
      },
    },
    column: {
      columnWidthRatio: 0.8,
      label: {
        position: 'middle',
      },
    },
  };

  const lineData = [
    { month: 'Jan', value: 100 },
    { month: 'Feb', value: 120 },
    { month: 'Mar', value: 80 },
  ];

  const columnData = [
    { category: 'A', value: 40 },
    { category: 'B', value: 60 },
    { category: 'C', value: 30 },
  ];

  return (
    <ConfigProvider {...config}>
      <div>
        <Line data={lineData} xField="month" yField="value" />
        <Column data={columnData} xField="category" yField="value" />
      </div>
    </ConfigProvider>
  );
};

Configuration Context

React context for accessing and consuming chart configuration values.

/**
 * Configuration context for sharing chart settings
 */
const ConfigContext: React.Context<ConfigValue>;

Usage Example:

import React, { useContext } from "react";
import { ConfigContext } from "@ant-design/plots";

const CustomChart: React.FC = () => {
  const config = useContext(ConfigContext);
  
  // Access global configuration
  const commonConfig = config?.common;
  const lineConfig = config?.line;
  
  return (
    <div>
      <p>Theme: {commonConfig?.theme}</p>
      <p>Line smooth: {lineConfig?.smooth ? 'Yes' : 'No'}</p>
    </div>
  );
};

Configuration Hierarchy

Configuration follows a specific hierarchy where more specific settings override general ones:

  1. Component Props (highest priority)
  2. Chart-specific Config (from ConfigProvider)
  3. Common Config (from ConfigProvider)
  4. Component Defaults (lowest priority)
// Configuration merge order (highest to lowest priority)
interface ConfigHierarchy {
  /** Direct component props */
  componentProps: ChartConfig;
  /** Chart type specific configuration */
  chartTypeConfig: ChartConfig;
  /** Common configuration for all charts */
  commonConfig: CommonConfig;
  /** Built-in component defaults */
  defaults: ChartConfig;
}

Example:

import React from "react";
import { ConfigProvider, Line } from "@ant-design/plots";

const ConfigHierarchyExample: React.FC = () => {
  return (
    <ConfigProvider
      common={{ theme: 'dark' }}           // Applied to all charts
      line={{ smooth: true, color: 'blue' }}  // Applied to Line charts only
    >
      <Line
        data={data}
        xField="x"
        yField="y"
        color="red"  // Overrides line.color from ConfigProvider
        // smooth: true comes from line config
        // theme: 'dark' comes from common config
      />
    </ConfigProvider>
  );
};

Common Configuration Options

Theme Configuration

interface ThemeConfig {
  /** Built-in theme name */
  theme?: 'default' | 'dark' | 'light';
  /** Custom theme object */
  themeObject?: {
    colors10?: string[];
    colors20?: string[];
    backgroundColor?: string;
    subColor?: string;
    semanticRed?: string;
    semanticGreen?: string;
    fontFamily?: string;
  };
}

Responsive Configuration

interface ResponsiveConfig {
  /** Enable responsive behavior */
  responsive?: boolean;
  /** Auto-fit to container */
  autoFit?: boolean;
  /** Container padding */
  padding?: number | number[] | 'auto';
  /** Responsive breakpoints */
  breakpoints?: {
    xs?: number;
    sm?: number;
    md?: number;
    lg?: number;
    xl?: number;
  };
}

Animation Configuration

interface AnimationConfig {
  /** Enable animations */
  animation?: boolean | {
    /** Appear animation */
    appear?: {
      animation?: string;
      delay?: number;
      duration?: number;
      easing?: string;
    };
    /** Enter animation */
    enter?: {
      animation?: string;
      delay?: number;
      duration?: number;
      easing?: string;
    };
    /** Update animation */
    update?: {
      animation?: string;
      delay?: number;
      duration?: number;
      easing?: string;
    };
    /** Leave animation */
    leave?: {
      animation?: string;
      delay?: number;
      duration?: number;
      easing?: string;
    };
  };
}

Interaction Configuration

interface InteractionConfig {
  /** Chart interactions */
  interactions?: Array<{
    type: string;
    cfg?: Record<string, any>;
  }>;
  /** Tooltip configuration */
  tooltip?: {
    showTitle?: boolean;
    showMarkers?: boolean;
    showCrosshairs?: boolean;
    marker?: {
      r?: number;
      stroke?: string;
      strokeWidth?: number;
    };
    crosshairs?: {
      type?: 'x' | 'y' | 'xy';
      line?: {
        style?: Record<string, any>;
      };
    };
  };
}

Custom Configuration Hooks

useConfig Hook

Hook for accessing configuration context within chart components.

/**
 * Hook for accessing chart configuration context
 * @returns Configuration values or undefined if outside provider
 */
function useConfig(): ConfigValue | undefined;

Usage Example:

import React from "react";
import { useConfig } from "@ant-design/plots";

const ChartWithConfig: React.FC = () => {
  const config = useConfig();
  
  const chartProps = {
    // Use config values with fallbacks
    theme: config?.common?.theme || 'default',
    smooth: config?.line?.smooth || false,
    // ... other props
  };
  
  return <SomeChart {...chartProps} />;
};

Best Practices

Configuration Organization

// Organize configurations by concern
const themeConfig = {
  common: {
    theme: 'dark',
    backgroundColor: '#1f1f1f',
    tooltip: { showTitle: false },
  },
};

const behaviorConfig = {
  common: {
    autoFit: true,
    animation: true,
  },
};

const chartSpecificConfig = {
  line: { smooth: true },
  column: { columnWidthRatio: 0.6 },
  pie: { innerRadius: 0.3 },
};

// Merge configurations
const fullConfig = {
  ...themeConfig,
  ...behaviorConfig,
  ...chartSpecificConfig,
};

Performance Considerations

// Memoize configuration to prevent unnecessary re-renders
const MyApp: React.FC = () => {
  const config = useMemo(() => ({
    common: {
      theme: 'dark',
      autoFit: true,
    },
    line: {
      smooth: true,
    },
  }), []);

  return (
    <ConfigProvider {...config}>
      {/* Chart components */}
    </ConfigProvider>
  );
};

Dynamic Configuration

// Update configuration based on state or props
const DynamicConfigApp: React.FC = () => {
  const [isDark, setIsDark] = useState(false);
  
  const config = useMemo(() => ({
    common: {
      theme: isDark ? 'dark' : 'light',
      backgroundColor: isDark ? '#1f1f1f' : '#ffffff',
    },
  }), [isDark]);

  return (
    <ConfigProvider {...config}>
      <button onClick={() => setIsDark(!isDark)}>
        Toggle Theme
      </button>
      {/* Charts automatically update with new theme */}
    </ConfigProvider>
  );
};