or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

content-formatting.mdevent-handling.mdindex.mdlabel-positioning.mdlabel-styling.mdmulti-label.mdplugin-integration.md
tile.json

label-styling.mddocs/

Label Styling

Comprehensive styling and appearance options for data labels including colors, fonts, borders, shadows, backgrounds, and visual effects.

Capabilities

Text Styling

Control the appearance of label text with color, fonts, and text effects.

interface TextStyling {
  /** Text color - supports CSS colors, gradients, and patterns
   * @default undefined (inherits from Chart.defaults.color) */
  color?: Indexable<Color> | Scriptable<Color>;
  
  /** Font configuration object
   * @default { family: undefined, lineHeight: 1.2, size: undefined, style: undefined, weight: null } */
  font?: Indexable<Font> | Scriptable<Font>;
  
  /** Multi-line text alignment
   * @default 'start' */
  textAlign?: Indexable<TextAlign> | Scriptable<TextAlign>;
  
  /** Text stroke (outline) color
   * @default undefined (no stroke) */
  textStrokeColor?: Indexable<Color> | Scriptable<Color>;
  
  /** Text stroke width in pixels
   * @default 0 (no stroke) */
  textStrokeWidth?: Indexable<number> | Scriptable<number>;
  
  /** Text shadow blur amount in pixels
   * @default 0 (no shadow) */
  textShadowBlur?: Indexable<number> | Scriptable<number>;
  
  /** Text shadow color
   * @default undefined (no shadow) */
  textShadowColor?: Indexable<Color> | Scriptable<Color>;
}

interface Font {
  family?: string;
  lineHeight?: string | number;
  size?: number;
  style?: 'normal' | 'italic' | 'oblique';
  weight?: 'normal' | 'bold' | 'bolder' | 'lighter' | number;
}

type TextAlign = 'left' | 'right' | 'start' | 'center' | 'end';
type Color = string | CanvasGradient | CanvasPattern;

Usage Examples:

// Basic text styling
datalabels: {
  color: '#333',
  font: {
    family: 'Arial',
    size: 14,
    weight: 'bold'
  }
}

// Text with stroke and shadow
datalabels: {
  color: 'white',
  textStrokeColor: 'black',
  textStrokeWidth: 2,
  textShadowColor: 'rgba(0,0,0,0.5)',
  textShadowBlur: 3
}

// Multi-line text alignment
datalabels: {
  textAlign: 'center',
  formatter: (value) => value.toString().split('').join('\n')
}

Background and Border Styling

Create visually distinct labels with backgrounds, borders, and rounded corners.

interface BackgroundStyling {
  /** Background color - null for transparent
   * @default null (no background) */
  backgroundColor?: Indexable<Color | null> | Scriptable<Color | null>;
  
  /** Border color - null for no border
   * @default null (no border) */
  borderColor?: Indexable<Color | null> | Scriptable<Color | null>;
  
  /** Border width in pixels
   * @default 0 (no border) */
  borderWidth?: Indexable<number> | Scriptable<number>;
  
  /** Border radius for rounded corners
   * @default 0 (not rounded) */
  borderRadius?: Indexable<number> | Scriptable<number>;
  
  /** Internal padding around text
   * @default { top: 4, right: 4, bottom: 4, left: 4 } */
  padding?: Indexable<Padding> | Scriptable<Padding>;
}

interface Padding {
  top?: number;
  right?: number;
  bottom?: number;
  left?: number;
}

Usage Examples:

// Label with background and border
datalabels: {
  backgroundColor: 'rgba(255, 255, 255, 0.8)',
  borderColor: 'blue',
  borderWidth: 2,
  borderRadius: 4,
  padding: 6
}

// Rounded pill-style labels
datalabels: {
  backgroundColor: 'darkblue',
  color: 'white',
  borderRadius: 20,
  padding: {
    top: 4,
    bottom: 4,
    left: 12,
    right: 12
  }
}

// Different padding per side
datalabels: {
  backgroundColor: 'lightgray',
  padding: {
    top: 2,
    right: 8,
    bottom: 2,
    left: 8
  }
}

Visual Effects

Control overall label visibility and opacity effects.

interface VisualEffects {
  /** Label visibility - true, false, or 'auto' for collision detection
   * @default true */
  display?: Indexable<boolean | string> | Scriptable<boolean | string>;
  
  /** Overall opacity from 0.0 (transparent) to 1.0 (opaque)
   * @default 1 (fully opaque) */
  opacity?: Indexable<number> | Scriptable<number>;
}

Usage Examples:

// Conditional display based on value
datalabels: {
  display: function(context) {
    return context.parsed.y > 10; // Only show for values > 10
  }
}

// Auto-hide overlapping labels
datalabels: {
  display: 'auto'
}

// Semi-transparent labels
datalabels: {
  opacity: 0.7,
  backgroundColor: 'black',
  color: 'white'
}

// Fade effect based on data
datalabels: {
  opacity: function(context) {
    const value = context.parsed.y;
    const max = Math.max(...context.dataset.data);
    return 0.3 + (0.7 * value / max); // Higher values more opaque
  }
}

Dynamic Styling

Use scriptable options for data-driven styling that changes based on context.

Usage Examples:

// Color based on value
datalabels: {
  color: function(context) {
    const value = context.parsed.y;
    return value > 50 ? 'green' : value > 25 ? 'orange' : 'red';
  }
}

// Font size based on dataset
datalabels: {
  font: function(context) {
    return {
      size: 10 + context.datasetIndex * 2,
      weight: context.active ? 'bold' : 'normal'
    };
  }
}

// Background based on chart area
datalabels: {
  backgroundColor: function(context) {
    const chart = context.chart;
    const gradient = chart.ctx.createLinearGradient(0, 0, 0, chart.height);
    gradient.addColorStop(0, 'rgba(255,0,0,0.8)');
    gradient.addColorStop(1, 'rgba(0,0,255,0.8)');
    return gradient;
  }
}

Responsive Styling

Adapt label appearance based on chart size and device characteristics.

Usage Examples:

// Responsive font sizes
datalabels: {
  font: function(context) {
    const width = context.chart.width;
    return {
      size: width < 400 ? 10 : width < 800 ? 12 : 14
    };
  }
}

// Hide labels on small screens
datalabels: {
  display: function(context) {
    return context.chart.width > 300;
  }
}