CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-plotly-js-dist

JavaScript data visualization library for creating interactive charts, graphs, and scientific visualizations

81

1.02x
Overview
Eval results
Files

layout-system.mddocs/

Layout System

Comprehensive layout controls for plot appearance, axes, legends, annotations, and interactive elements. The layout system controls everything outside of the actual data traces.

Core Layout Structure

interface Layout {
  // Plot dimensions and positioning
  width?: number;
  height?: number;
  margin?: MarginConfig;
  autosize?: boolean;
  
  // Plot styling
  title?: string | TitleConfig;
  font?: FontConfig;
  paper_bgcolor?: string;
  plot_bgcolor?: string;
  colorway?: string[];
  template?: string | TemplateConfig;
  
  // Axes configuration  
  xaxis?: AxisConfig;
  yaxis?: AxisConfig;
  scene?: Scene3DConfig; // For 3D plots
  
  // Interactive elements
  legend?: LegendConfig;
  annotations?: AnnotationConfig[];
  shapes?: ShapeConfig[];
  images?: ImageConfig[];
  
  // Controls
  updatemenus?: UpdateMenuConfig[];
  sliders?: SliderConfig[];
  
  // Layout modes
  barmode?: 'stack' | 'group' | 'overlay' | 'relative';
  boxmode?: 'group' | 'overlay';
  dragmode?: 'zoom' | 'pan' | 'select' | 'lasso' | 'orbit' | 'turntable' | false;
  hovermode?: 'x' | 'y' | 'closest' | 'x unified' | 'y unified' | false;
  
  // Grid and subplots
  grid?: GridConfig;
  
  // Geographic
  geo?: GeoConfig;
  mapbox?: MapboxConfig;
  
  // Calendars and localization
  calendar?: string;
  
  // Animation
  transition?: TransitionConfig;
}

Plot Dimensions and Margins

Size Configuration

interface MarginConfig {
  l?: number; // Left margin
  r?: number; // Right margin  
  t?: number; // Top margin
  b?: number; // Bottom margin
  pad?: number; // Padding between plotting area and margins
  autoexpand?: boolean; // Auto-expand margins for labels
}

Usage Examples:

// Fixed size plot
const layout = {
  width: 800,
  height: 600,
  margin: {
    l: 50,
    r: 50,
    t: 100,
    b: 50
  }
};

// Responsive plot that fills container
const responsiveLayout = {
  autosize: true,
  margin: { l: 40, r: 40, t: 40, b: 40 }
};

// Auto-expanding margins for long labels
const autoMarginLayout = {
  margin: {
    l: 80,
    r: 20,
    t: 60,
    b: 60,
    autoexpand: true
  }
};

Titles and Text

Title Configuration

interface TitleConfig {
  text?: string;
  font?: FontConfig;
  x?: number; // 0-1, horizontal position
  y?: number; // 0-1, vertical position  
  xanchor?: 'auto' | 'left' | 'center' | 'right';
  yanchor?: 'auto' | 'top' | 'middle' | 'bottom';
  xref?: 'container' | 'paper';
  yref?: 'container' | 'paper';
  pad?: PaddingConfig;
}

interface FontConfig {
  family?: string;
  size?: number;
  color?: string;
}

interface PaddingConfig {
  t?: number;
  b?: number;
  l?: number;
  r?: number;
}

Usage Examples:

// Simple title
const layout = {
  title: 'My Chart Title'
};

// Advanced title configuration
const advancedTitle = {
  title: {
    text: 'Advanced Chart Title',
    font: {
      family: 'Arial, sans-serif',
      size: 24,
      color: '#333'
    },
    x: 0.5, // Center horizontally
    y: 0.95, // Near top
    xanchor: 'center',
    yanchor: 'top'
  }
};

// Multi-line title with HTML
const htmlTitle = {
  title: {
    text: 'Main Title<br><sub>Subtitle with smaller text</sub>',
    font: { size: 18 }
  }
};

Axes Configuration

Axis Properties

interface AxisConfig {
  // Axis title
  title?: string | AxisTitleConfig;
  
  // Range and scaling
  range?: [number, number] | [string, string];
  autorange?: boolean | 'reversed';
  type?: 'linear' | 'log' | 'date' | 'category' | 'multicategory';
  
  // Ticks
  tickmode?: 'auto' | 'linear' | 'array';
  tick0?: number;
  dtick?: number | string;
  tickvals?: number[] | string[];
  ticktext?: string[];
  tickangle?: number;
  tickfont?: FontConfig;
  tickformat?: string;
  tickprefix?: string;
  ticksuffix?: string;
  
  // Grid and lines
  showgrid?: boolean;
  gridcolor?: string;
  gridwidth?: number;
  showline?: boolean;
  linecolor?: string;
  linewidth?: number;
  mirror?: boolean | 'ticks' | 'all' | 'allticks';
  
  // Axis line and zero line
  zeroline?: boolean;
  zerolinecolor?: string;
  zerolinewidth?: number;
  
  // Positioning
  side?: 'top' | 'bottom' | 'left' | 'right';
  position?: number; // 0-1
  anchor?: string; // Other axis id
  overlaying?: string; // Other axis id
  
  // Spikes (crosshair lines)
  showspikes?: boolean;
  spikecolor?: string;
  spikethickness?: number;
  spikedash?: string;
  spikemode?: 'toaxis' | 'across' | 'marker';
  spikesnap?: 'data' | 'cursor' | 'hovered data';
  
  // Visibility
  visible?: boolean;
  showticklabels?: boolean;
  
  // Categorical axes
  categoryorder?: 'trace' | 'category ascending' | 'category descending' | 'array' | 'total ascending' | 'total descending' | 'min ascending' | 'min descending' | 'max ascending' | 'max descending' | 'sum ascending' | 'sum descending' | 'mean ascending' | 'mean descending' | 'median ascending' | 'median descending';
  categoryarray?: string[];
  
  // Constraints
  constrain?: 'range' | 'domain';
  constraintoward?: 'left' | 'center' | 'right' | 'top' | 'middle' | 'bottom';
  
  // Calendar
  calendar?: string;
}

interface AxisTitleConfig {
  text?: string;
  font?: FontConfig;
  standoff?: number;
}

Usage Examples:

// Basic axis configuration
const layout = {
  xaxis: {
    title: 'Time (seconds)',
    range: [0, 10],
    showgrid: true,
    gridcolor: 'lightgray'
  },
  yaxis: {
    title: 'Temperature (°C)',
    range: [-10, 40],
    zeroline: true,
    zerolinecolor: 'red',
    zerolinewidth: 2
  }
};

// Logarithmic axis
const logLayout = {
  yaxis: {
    type: 'log',
    title: 'Log Scale',
    range: [0, 2], // 10^0 to 10^2
    dtick: 1 // Major tick every power of 10
  }
};

// Date axis
const dateLayout = {
  xaxis: {
    type: 'date',
    title: 'Date',
    tickformat: '%Y-%m-%d',
    range: ['2023-01-01', '2023-12-31']
  }
};

// Categorical axis with custom order
const catLayout = {
  xaxis: {
    type: 'category',
    categoryorder: 'array',
    categoryarray: ['Small', 'Medium', 'Large', 'X-Large']
  }
};

// Dual y-axes
const dualAxisLayout = {
  yaxis: {
    title: 'Primary Y-axis',
    side: 'left'
  },
  yaxis2: {
    title: 'Secondary Y-axis',
    side: 'right',
    overlaying: 'y',
    range: [0, 100]
  }
};

Visual Styling

Color and Appearance

interface TemplateConfig {
  data?: {
    scatter?: Partial<ScatterTrace>[];
    bar?: Partial<BarTrace>[];
    [traceType: string]: Partial<any>[];
  };
  layout?: Partial<Layout>;
}

Usage Examples:

// Basic styling
const styledLayout = {
  paper_bgcolor: 'white',
  plot_bgcolor: 'rgba(240, 240, 240, 0.5)',
  font: {
    family: 'Arial, sans-serif',
    size: 14,
    color: '#333'
  },
  colorway: ['#1f77b4', '#ff7f0e', '#2ca02c', '#d62728', '#9467bd']
};

// Dark theme
const darkLayout = {
  paper_bgcolor: '#1e1e1e',
  plot_bgcolor: '#2d2d2d',
  font: { color: 'white' },
  xaxis: {
    gridcolor: '#404040',
    linecolor: '#666',
    tickcolor: 'white'
  },
  yaxis: {
    gridcolor: '#404040', 
    linecolor: '#666',
    tickcolor: 'white'
  }
};

// Custom template
const customTemplate = {
  layout: {
    colorway: ['#FF6B6B', '#4ECDC4', '#45B7D1', '#96CEB4', '#FECA57'],
    font: { family: 'Roboto, sans-serif' },
    paper_bgcolor: '#F8F9FA',
    plot_bgcolor: 'white'
  },
  data: {
    scatter: [{
      marker: { line: { width: 0.5 } }
    }],
    bar: [{
      marker: { line: { width: 1.5, color: 'white' } }
    }]
  }
};

Interactive Elements

Hover Configuration

// Hover behavior
const hoverLayout = {
  hovermode: 'x unified', // Show all y-values for same x
  hoverlabel: {
    bgcolor: 'white',
    bordercolor: 'black',
    font: { size: 16, family: 'Arial' }
  }
};

// Disable hover
const noHoverLayout = {
  hovermode: false
};

// Closest point hover
const closestLayout = {
  hovermode: 'closest'
};

Drag and Selection Modes

// Zoom and pan controls
const interactiveLayout = {
  dragmode: 'zoom', // or 'pan', 'select', 'lasso'
  selectdirection: 'diagonal' // or 'horizontal', 'vertical'
};

// Disable interactions
const staticLayout = {
  dragmode: false,
  scrollZoom: false,
  doubleClick: false
};

Subplot Configuration

Grid Layouts

interface GridConfig {
  rows?: number;
  columns?: number;
  pattern?: 'independent' | 'coupled';
  xaxes?: string[];
  yaxes?: string[];
  subplots?: string[][];
  xgap?: number; // 0-1
  ygap?: number; // 0-1
  domain?: {
    x?: [number, number];
    y?: [number, number];
  };
}

Usage Examples:

// 2x2 subplot grid
const subplotLayout = {
  grid: {
    rows: 2,
    columns: 2,
    pattern: 'independent',
    subplots: [
      ['xy', 'x2y'],
      ['xy2', 'x2y2']
    ]
  },
  xaxis: { domain: [0, 0.48] },
  xaxis2: { domain: [0.52, 1] },
  yaxis: { domain: [0.52, 1] },
  yaxis2: { domain: [0, 0.48] }
};

// Shared x-axis subplots
const sharedXLayout = {
  xaxis: { domain: [0, 1] },
  yaxis: { domain: [0.55, 1] },
  yaxis2: { domain: [0, 0.45] },
  // Both traces use same xaxis, different yaxis
};

3D Scene Configuration

interface Scene3DConfig {
  camera?: {
    eye?: { x?: number; y?: number; z?: number; };
    center?: { x?: number; y?: number; z?: number; };
    up?: { x?: number; y?: number; z?: number; };
    projection?: { type?: 'perspective' | 'orthographic'; };
  };
  xaxis?: Axis3DConfig;
  yaxis?: Axis3DConfig;
  zaxis?: Axis3DConfig;
  aspectmode?: 'auto' | 'cube' | 'data' | 'manual';
  aspectratio?: { x?: number; y?: number; z?: number; };
  bgcolor?: string;
  dragmode?: 'orbit' | 'turntable' | 'zoom' | 'pan' | false;
  hovermode?: 'closest' | false;
}

interface Axis3DConfig extends AxisConfig {
  backgroundcolor?: string;
  showbackground?: boolean;
  showaxeslabels?: boolean;
}

Usage Examples:

// 3D scene configuration
const scene3DLayout = {
  scene: {
    camera: {
      eye: { x: 1.2, y: 1.2, z: 1.2 },
      center: { x: 0, y: 0, z: 0 }
    },
    xaxis: {
      title: 'X Axis',
      showbackground: true,
      backgroundcolor: 'rgba(230, 230, 230, 0.5)'
    },
    yaxis: {
      title: 'Y Axis', 
      showbackground: true,
      backgroundcolor: 'rgba(230, 230, 230, 0.5)'
    },
    zaxis: {
      title: 'Z Axis',
      showbackground: true,
      backgroundcolor: 'rgba(230, 230, 230, 0.5)'
    },
    aspectmode: 'cube',
    dragmode: 'orbit'
  }
};

Geographic Configuration

interface GeoConfig {
  resolution?: 110 | 50;
  scope?: 'world' | 'usa' | 'europe' | 'asia' | 'africa' | 'north america' | 'south america';
  projection?: {
    type?: 'equirectangular' | 'mercator' | 'orthographic' | 'natural earth' | 'kavrayskiy7' | 'miller' | 'robinson' | 'eckert4' | 'azimuthal equal area' | 'azimuthal equidistant' | 'conic equal area' | 'conic conformal' | 'conic equidistant' | 'gnomonic' | 'stereographic' | 'mollweide' | 'hammer' | 'transverse mercator' | 'albers usa' | 'winkel tripel' | 'aitoff' | 'sinusoidal';
    rotation?: { lon?: number; lat?: number; roll?: number; };
    scale?: number;
  };
  center?: { lon?: number; lat?: number; };
  showland?: boolean;
  landcolor?: string;
  showocean?: boolean;
  oceancolor?: string;
  showlakes?: boolean;
  lakecolor?: string;
  showcountries?: boolean;
  countrycolor?: string;
  countrywidth?: number;
  showrivers?: boolean;
  rivercolor?: string;
  riverwidth?: number;
  showcoastlines?: boolean;
  coastlinecolor?: string;
  coastlinewidth?: number;
  bgcolor?: string;
}

Advanced Layout Patterns

Responsive Design

// Responsive layout that adapts to container
const responsiveLayout = {
  autosize: true,
  margin: { l: 50, r: 50, t: 50, b: 50, autoexpand: true },
  font: { size: 12 },
  legend: { 
    orientation: 'h',
    y: -0.2,
    x: 0.5,
    xanchor: 'center'
  }
};

// Mobile-friendly configuration
const mobileLayout = {
  width: 350,
  height: 250,
  margin: { l: 40, r: 20, t: 40, b: 40 },
  font: { size: 10 },
  showlegend: false,
  dragmode: false
};

Multi-Chart Dashboards

// Dashboard with multiple chart areas
const dashboardLayout = {
  grid: {
    rows: 2,
    columns: 2,
    pattern: 'independent'
  },
  annotations: [
    {
      text: 'Chart 1',
      x: 0.25,
      y: 0.95,
      xref: 'paper',
      yref: 'paper',
      showarrow: false,
      font: { size: 16, color: 'blue' }
    },
    {
      text: 'Chart 2', 
      x: 0.75,
      y: 0.95,
      xref: 'paper',
      yref: 'paper',
      showarrow: false,
      font: { size: 16, color: 'red' }
    }
  ]
};

Performance Considerations

  • Use autosize: true with CSS for responsive designs
  • Minimize the number of annotations and shapes for better performance
  • Consider disabling unnecessary features (grid, zeroline) for cleaner, faster rendering
  • Use appropriate axis ranges to avoid auto-ranging calculations
  • For animations, pre-define layout configurations in frames

Install with Tessl CLI

npx tessl i tessl/npm-plotly-js-dist

docs

animation.md

chart-types.md

core-plotting.md

data-streaming.md

data-updates.md

export-utilities.md

index.md

interactive-components.md

layout-system.md

trace-management.md

tile.json