ChartSpire

Appearance

Custom Styles ​

ChartSpire provides a powerful and flexible custom styles system that allows you to override default chart styling with your own custom styles. This feature enables you to create branded chart experiences, implement accessibility features, or simply customize the visual appearance to match your application's design system.

Overview ​

The custom styles system supports multiple levels of style overrides with a clear precedence hierarchy:

  • Global styles - Applied to all themes
  • Theme-category styles - Applied to light or dark themes
  • Theme-specific styles - Applied to individual themes by name

Custom styles are automatically preserved when switching themes, and they integrate seamlessly with ChartSpire's existing theme system.

TypeScript Support ​

The custom styles feature is fully typed for an excellent developer experience:

typescript
import { CustomStyleOverrides, Styles, DeepPartial } from 'chartspire'

const typedCustomStyles: CustomStyleOverrides = {
  global: {
    candle: {
      bar: {
        upColor: '#00ff00',
        downColor: '#ff0000'
      }
    }
  }
}

Available Types ​

  • **CustomStyleOverrides**: Main interface for custom style configuration
  • **Styles**: Complete styles interface from the underlying chart library
  • **DeepPartial<Styles>**: Partial styles interface allowing you to override only specific properties

Type Structure ​

typescript
interface CustomStyleOverrides {
  /** Styles to apply to all themes */
  global?: DeepPartial<Styles>
  /** Styles to apply to light themes only */
  light?: DeepPartial<Styles>
  /** Styles to apply to dark themes only */
  dark?: DeepPartial<Styles>
  /** Styles to apply to specific themes by name */
  themes?: Record<string, DeepPartial<Styles>>
}

This ensures type safety and provides autocomplete suggestions for all available style properties.

Getting Started ​

Basic Setup ​

The simplest way to use custom styles is to define global overrides that apply to all themes:

typescript
import { ChartSpire, SYMBOL_TYPE, type CustomStyleOverrides } from 'chartspire'

// Basic custom styles
const basicCustomStyles: CustomStyleOverrides = {
  // Global styles applied to all themes
  global: {
    candle: {
      priceMark: {
        high: { color: '#ff6b6b' },
        low: { color: '#4ecdc4' }
      }
    },
    grid: {
      horizontal: { show: true, size: 1 },
      vertical: { show: true, size: 1 }
    }
  }
}

// Initialize ChartSpire with custom styles
const chart = new ChartSpire({
  container: document.getElementById('chart-container')!,
  rootContainer: document.getElementById('chart-container')!,
  dataFeed: new BinanceDataFeed(),
  enabledSymbolTypes: [SYMBOL_TYPE.CRYPTO],
  symbol: { symbol: 'BTCUSDT', type: SYMBOL_TYPE.CRYPTO },
  interval: { multiplier: 1, timespan: 'minute', text: '1m' },
  theme: 'Dark Theme',
  // Pass custom styles during initialization
  customStyles: basicCustomStyles,
  // ... other options
})

Theme-Specific Customization ​

For more sophisticated styling, you can define different styles for light and dark themes:

typescript
// Theme-specific custom styles
const themeSpecificCustomStyles: CustomStyleOverrides = {
  // Styles for light themes
  light: {
    grid: {
      horizontal: { color: '#e8e8e8' },
      vertical: { color: '#e8e8e8' }
    },
    candle: {
      tooltip: {
        labels: ['O', 'H', 'L', 'C', 'V'],
        text: { color: '#333333' }
      }
    }
  },
  // Styles for dark themes
  dark: {
    grid: {
      horizontal: { color: '#404040' },
      vertical: { color: '#404040' }
    },
    candle: {
      tooltip: {
        labels: ['O', 'H', 'L', 'C', 'V'],
        text: { color: '#ffffff' }
      }
    }
  }
}

// Apply theme-specific styles
chart.setCustomStyles(themeSpecificCustomStyles)

Individual Theme Customization ​

You can also target specific themes by name for the most precise control:

typescript
// Specific theme custom styles
const specificThemeCustomStyles: CustomStyleOverrides = {
  themes: {
    'Dark Theme': {
      candle: {
        type: 'candle_solid',
        bar: {
          upColor: '#26a69a',
          downColor: '#ef5350'
        }
      }
    },
    'Light Theme 1': {
      candle: {
        type: 'candle_solid',
        bar: {
          upColor: '#4caf50',
          downColor: '#f44336'
        }
      }
    }
  }
}

// Apply specific theme styles
chart.setCustomStyles(specificThemeCustomStyles)

Advanced Configuration ​

Multi-Level Style Overrides ​

You can combine all override levels for sophisticated styling control:

typescript
// Comprehensive custom styles with multiple override levels
const comprehensiveCustomStyles: CustomStyleOverrides = {
  // Global overrides (applied to all themes)
  global: {
    candle: {
      priceMark: {
        high: { color: '#ff9800' },
        low: { color: '#2196f3' }
      }
    }
  },
  // Light theme overrides
  light: {
    grid: {
      horizontal: { color: '#f0f0f0', size: 1 },
      vertical: { color: '#f0f0f0', size: 1 }
    },
    xAxis: {
      axisLine: { color: '#d0d0d0' }
    },
    yAxis: {
      axisLine: { color: '#d0d0d0' }
    }
  },
  // Dark theme overrides
  dark: {
    grid: {
      horizontal: { color: '#333333', size: 1 },
      vertical: { color: '#333333', size: 1 }
    },
    xAxis: {
      axisLine: { color: '#555555' }
    },
    yAxis: {
      axisLine: { color: '#555555' }
    }
  },
  // Specific theme overrides (highest precedence)
  themes: {
    'Blue Theme': {
      candle: {
        bar: {
          upColor: '#1976d2',
          downColor: '#d32f2f'
        }
      }
    }
  }
}

chart.setCustomStyles(comprehensiveCustomStyles)

Complex Styling Configuration ​

For advanced use cases, you can define comprehensive styling with nested overrides:

typescript
// Complex styling with nested overrides
const complexCustomStyles: CustomStyleOverrides = {
  global: {
    candle: {
      type: 'candle_solid',
      bar: {
        upColor: '#00e676',
        downColor: '#ff5252',
        upBorderColor: '#00c853',
        downBorderColor: '#d50000',
        upWickColor: '#00c853',
        downWickColor: '#d50000'
      },
      tooltip: {
        showRule: 'always',
        showType: 'standard',
        labels: ['Open', 'High', 'Low', 'Close', 'Volume'],
        text: {
          size: 12,
          family: 'Arial',
          weight: 'normal'
        }
      }
    }
  },
  light: {
    candle: {
      tooltip: {
        text: { color: '#333333' }
      }
    }
  },
  dark: {
    candle: {
      tooltip: {
        text: { color: '#ffffff' }
      }
    }
  }
}

chart.setCustomStyles(complexCustomStyles)

API Reference ​

Setting Custom Styles ​

typescript
// Set custom styles after initialization
chart.setCustomStyles(customStyles)

Getting Current Custom Styles ​

typescript
// Get current custom styles
const currentCustomStyles = chart.getCustomStyles()
console.log('Current custom styles:', currentCustomStyles)

Checking if Custom Styles are Applied ​

typescript
// Check if custom styles are applied
if (chart.hasCustomStyles()) {
  console.log('Custom styles are currently applied')
}

Clearing Custom Styles ​

typescript
// Clear custom styles (revert to defaults)
chart.clearCustomStyles()

Style Override Precedence ​

The custom styles system applies overrides in the following order (from lowest to highest precedence):

  1. Default Theme Styles (base styles)
  2. Global Overrides (customStyles.global)
  3. Light/Dark Theme Overrides (customStyles.light or customStyles.dark)
  4. Specific Theme Overrides (customStyles.themes['Theme Name'])

Higher precedence styles will override lower precedence styles for the same properties.

Theme Integration ​

Custom styles are automatically preserved when switching themes:

typescript
// Theme switching with custom styles preserved
chart.setTheme('Light Theme 1')
// Custom styles will be automatically applied to the new theme

This ensures that your customizations remain consistent across theme changes, while still allowing theme-specific overrides to take effect.

Note: For more information about ChartSpire's theming system, including built-in themes, custom theme creation, and external storage options, see the Theme Customization documentation.

Common Use Cases ​

Brand Customization ​

Implement your company's brand colors and styling:

typescript
// Company brand colors
const brandCustomStyles: CustomStyleOverrides = {
  global: {
    candle: {
      bar: {
        upColor: '#1976d2',    // Company blue
        downColor: '#d32f2f'   // Company red
      }
    }
  }
}

chart.setCustomStyles(brandCustomStyles)

Accessibility Enhancement ​

Create high contrast styles for better accessibility:

typescript
// High contrast styles for accessibility
const highContrastStyles: CustomStyleOverrides = {
  global: {
    grid: {
      horizontal: { color: '#ffffff', size: 2 },
      vertical: { color: '#ffffff', size: 2 }
    },
    candle: {
      bar: {
        upColor: '#00ff00',
        downColor: '#ff0000',
        upBorderColor: '#ffffff',
        downBorderColor: '#ffffff'
      }
    }
  }
}

chart.setCustomStyles(highContrastStyles)

Dark Mode Optimization ​

Fine-tune dark theme appearance:

typescript
// Optimized dark mode styles
const darkModeStyles: CustomStyleOverrides = {
  dark: {
    grid: {
      horizontal: { color: '#2a2a2a' },
      vertical: { color: '#2a2a2a' }
    },
    candle: {
      tooltip: {
        text: { color: '#e0e0e0' }
      }
    }
  }
}

chart.setCustomStyles(darkModeStyles)

Copyright © 2024-2025 ChartSpire