Lines Chart

Overview

The lines chart displays connections between two or more points, making it ideal for visualizing flows, migrations, routes, and relationships in geographic or abstract coordinate systems. Lines can be straight or curved, animated or static, and support various visual effects.

When to Use

Use lines charts when you need to:

Visualize migration flows or movements between locations
Show network connections and routes
Display trade relationships between regions
Represent flight paths or shipping routes
Illustrate data flow in systems or processes
Create Sankey-like flow diagrams on maps
Show relationships between abstract points

Basic Configuration

The lines chart is configured through the LinesSeriesOption interface, supporting multiple coordinate systems.

interface LinesSeriesOption {
  type: 'lines'
  coordinateSystem?: string
  data?: LinesDataItemOption[]
  polyline?: boolean
  lineStyle?: {
    curveness?: number
    // ... other line style options
  }
  effect?: {
    show?: boolean
    period?: number
    symbol?: string
    // ... other effect options
  }
}

Complete Example

import * as echarts from 'echarts';

const chart = echarts.init(document.getElementById('main'));

const option = {
  title: {
    text: 'Migration Flow Between Cities'
  },
  tooltip: {
    trigger: 'item',
    formatter: function(params) {
      return params.data.fromName + ' → ' + params.data.toName;
    }
  },
  geo: {
    map: 'USA',
    roam: true,
    itemStyle: {
      areaColor: '#f3f3f3',
      borderColor: '#999'
    }
  },
  series: [
    {
      name: 'Migration',
      type: 'lines',
      coordinateSystem: 'geo',
      data: [
        {
          fromName: 'New York',
          toName: 'Los Angeles',
          coords: [
            [-74.006, 40.7128],  // NYC [longitude, latitude]
            [-118.2437, 34.0522]  // LA
          ]
        },
        {
          fromName: 'Chicago',
          toName: 'Houston',
          coords: [
            [-87.6298, 41.8781],
            [-95.3698, 29.7604]
          ]
        }
      ],
      lineStyle: {
        color: '#5470c6',
        width: 2,
        curveness: 0.2,  // Curved lines
        opacity: 0.6
      },
      effect: {
        show: true,
        period: 4,
        symbol: 'arrow',
        symbolSize: 8,
        trailLength: 0.1
      }
    }
  ]
};

chart.setOption(option);

Key Options

coords

number[][]

required

Array of coordinate pairs defining the line path. For basic lines, use two points [[x1,y1], [x2,y2]]. For polylines, use multiple points.

// Simple line from point A to point B
coords: [
  [116.4074, 39.9042],  // Beijing
  [-74.006, 40.7128]     // New York
]

// Polyline with multiple waypoints (requires polyline: true)
coords: [
  [116.4074, 39.9042],
  [121.4737, 31.2304],
  [139.6917, 35.6895]
]

lineStyle.curveness

number

default:"0"

Curvature of the line. Value ranges from 0 (straight) to 1 (highly curved). Positive values curve one direction, negative values curve the opposite direction.

lineStyle: {
  curveness: 0.2   // Slight curve
}

lineStyle: {
  curveness: -0.3  // Curve in opposite direction
}

effect

object

Animated visual effect that moves along the line, useful for showing direction and flow.

effect: {
  show: true,
  period: 4,          // Duration of one cycle in seconds
  constantSpeed: 0,   // Or use constant speed (px/sec)
  symbol: 'arrow',    // Symbol to animate
  symbolSize: 6,
  loop: true,         // Whether to loop the animation
  trailLength: 0.2    // Length of trail (0-1)
}

effect.show

boolean

default:"false"

Whether to show the animated effect along the line.

effect: {
  show: true
}

effect.period

number

default:"4"

Duration of one animation cycle in seconds. Ignored if constantSpeed is set.

effect: {
  period: 6  // Slower animation
}

effect.constantSpeed

number

default:"0"

Constant speed in pixels per second. When set to a value greater than 0, this overrides the period setting.

effect: {
  constantSpeed: 100  // Move at 100 pixels per second
}

effect.symbol

string

default:"'circle'"

Symbol type for the moving effect. Options include: 'circle', 'rect', 'roundRect', 'triangle', 'diamond', 'pin', 'arrow', or a custom SVG path.

effect: {
  symbol: 'arrow'  // Directional arrow
}

effect.trailLength

number

default:"0.2"

Length of the trail effect, ranging from 0 to 1. A value of 0.2 means the trail covers 20% of the line length.

effect: {
  trailLength: 0.4  // Longer trail
}

polyline

boolean

default:"false"

Whether lines are polylines with multiple segments. When true, the coords array can contain more than 2 points. Note: polylines do not support curveness, labels, or some animations.

polyline: true,
data: [{
  coords: [
    [116.4, 39.9],
    [121.5, 31.2],
    [139.7, 35.7],
    [151.2, -33.9]
  ]
}]

coordinateSystem

string

default:"'geo'"

The coordinate system to use for the lines:

'geo': Geographic coordinate system (default)
'cartesian2d': 2D rectangular coordinate system
'polar': Polar coordinate system
'calendar': Calendar coordinate system

coordinateSystem: 'geo'

symbol

string[] | string

Symbol at the start and end of lines. Can be a single value or array [startSymbol, endSymbol].

symbol: ['none', 'arrow']  // Arrow at end only
symbolSize: [0, 10]         // Size for each symbol

lineStyle

LineStyleOption

Visual style of the lines.

lineStyle: {
  color: '#5470c6',
  width: 2,
  opacity: 0.6,
  type: 'solid',  // 'solid', 'dashed', 'dotted'
  curveness: 0.2
}

large

boolean

default:"false"

Enable optimization for large-scale line data. Useful when rendering thousands of lines.

large: true,
largeThreshold: 2000

Data Format

Lines chart data follows a specific structure:

// Basic format with coords
data: [
  {
    coords: [[116.4, 39.9], [121.5, 31.2]],  // Required
    fromName: 'Beijing',  // Optional
    toName: 'Shanghai',   // Optional
    value: 100            // Optional, for tooltip/visual mapping
  },
  {
    coords: [[139.7, 35.7], [-74.0, 40.7]]
  }
]

// With per-line styling
data: [
  {
    coords: [[0, 0], [100, 100]],
    lineStyle: {
      color: '#f00',
      width: 3,
      curveness: 0.3
    },
    effect: {
      period: 2,
      symbolSize: 10
    }
  }
]

// Flat array format for large datasets
data: [
  2, 116.4, 39.9, 121.5, 31.2,  // Points count (2), then x1,y1,x2,y2
  3, 139.7, 35.7, 151.2, -33.9, -118.2, 34.0  // 3 points
]

Advanced Features

Migration Flow with Varying Width

series: [{
  type: 'lines',
  coordinateSystem: 'geo',
  data: [
    {
      coords: [[-74.006, 40.7128], [-118.2437, 34.0522]],
      value: 1000,  // Number of migrants
      lineStyle: {
        width: 3,
        color: '#5470c6'
      }
    },
    {
      coords: [[-87.6298, 41.8781], [-95.3698, 29.7604]],
      value: 500,
      lineStyle: {
        width: 1.5,
        color: '#5470c6'
      }
    }
  ],
  lineStyle: {
    curveness: 0.2,
    opacity: 0.6
  },
  effect: {
    show: true,
    symbol: 'arrow',
    symbolSize: 8,
    trailLength: 0.2
  }
}]

Flight Routes Network

const routes = [
  { from: [116.4, 39.9], to: [139.7, 35.7], flights: 50 },
  { from: [121.5, 31.2], to: [-74.0, 40.7], flights: 30 },
  { from: [139.7, 35.7], to: [151.2, -33.9], flights: 45 }
];

const option = {
  geo: { map: 'world' },
  series: [{
    type: 'lines',
    coordinateSystem: 'geo',
    data: routes.map(route => ({
      coords: [route.from, route.to],
      value: route.flights,
      lineStyle: {
        width: route.flights / 20,  // Width based on frequency
        color: '#91cc75',
        curveness: 0.2
      }
    })),
    effect: {
      show: true,
      period: 6,
      trailLength: 0.1,
      symbol: 'circle',
      symbolSize: 4
    }
  }]
};

Polyline Route with Waypoints

series: [{
  type: 'lines',
  coordinateSystem: 'geo',
  polyline: true,  // Enable multi-segment lines
  data: [
    {
      coords: [
        [-74.006, 40.7128],   // New York
        [-87.6298, 41.8781],  // Chicago (waypoint)
        [-118.2437, 34.0522]  // Los Angeles
      ],
      lineStyle: {
        color: '#ee6666',
        width: 2
      }
    }
  ],
  effect: {
    show: true,
    constantSpeed: 50
  }
}]

Network Connections on Cartesian

const option = {
  xAxis: { type: 'value', min: 0, max: 100 },
  yAxis: { type: 'value', min: 0, max: 100 },
  series: [
    {
      type: 'lines',
      coordinateSystem: 'cartesian2d',
      data: [
        { coords: [[10, 10], [50, 80]] },
        { coords: [[20, 30], [70, 40]] },
        { coords: [[50, 80], [90, 20]] }
      ],
      lineStyle: {
        curveness: 0.3,
        color: '#5470c6',
        width: 2
      },
      effect: {
        show: true,
        symbol: 'circle',
        symbolSize: 5,
        period: 3
      }
    }
  ]
};

Bidirectional Flow

series: [
  {
    name: 'Outbound',
    type: 'lines',
    coordinateSystem: 'geo',
    data: outboundData,
    lineStyle: {
      color: '#5470c6',
      curveness: 0.2
    },
    effect: {
      show: true,
      symbol: 'arrow',
      symbolSize: 6
    }
  },
  {
    name: 'Inbound',
    type: 'lines',
    coordinateSystem: 'geo',
    data: inboundData,
    lineStyle: {
      color: '#91cc75',
      curveness: -0.2  // Curve in opposite direction
    },
    effect: {
      show: true,
      symbol: 'arrow',
      symbolSize: 6
    }
  }
]

Performance Tips

Use large mode for datasets with thousands of lines:
```
large: true,
largeThreshold: 2000
```
Disable effects for many lines to improve performance:
```
effect: { show: false }
```

Use flat array format for very large datasets:

data: [2, x1, y1, x2, y2, 2, x3, y3, x4, y4, ...]

Progressive rendering for massive datasets:

progressive: 500,
progressiveThreshold: 1000

Common Use Cases

Migration Map

Set curveness between 0.2-0.4 for natural flow
Use effect.symbol: 'arrow' to show direction
Vary line width based on migration volume

Flight Routes

Use polylines for multi-stop routes
Set effect.constantSpeed for realistic movement
Apply different colors for different airlines

Network Topology

Use coordinateSystem: 'cartesian2d' for abstract networks
Set curveness to avoid line overlap
Combine with scatter series for nodes

Source Reference

The lines chart implementation can be found in:

Series model: src/chart/lines/LinesSeries.ts:147-429
Type definitions: src/chart/lines/LinesSeries.ts:75-145
Default options: src/chart/lines/LinesSeries.ts:385-428
Coords format: src/chart/lines/LinesSeries.ts:75,107,210-223
Effect options: src/chart/lines/LinesSeries.ts:126,400-408

Basic Charts

Advanced Charts

Statistical Charts

Special Charts

Overview

When to Use

Basic Configuration

Complete Example

Key Options

Data Format

Advanced Features

Migration Flow with Varying Width

Flight Routes Network

Polyline Route with Waypoints

Network Connections on Cartesian

Bidirectional Flow

Performance Tips

Common Use Cases

Migration Map

Flight Routes

Network Topology

Source Reference

Build docs developers (and LLMs) love

Basic Charts

Advanced Charts

Statistical Charts

Special Charts

Documentation Index

​Overview

​When to Use

​Basic Configuration

​Complete Example

​Key Options

​Data Format

​Advanced Features

​Migration Flow with Varying Width

​Flight Routes Network

​Polyline Route with Waypoints

​Network Connections on Cartesian

​Bidirectional Flow

​Performance Tips

​Common Use Cases

​Migration Map

​Flight Routes

​Network Topology

​Source Reference

Build docs developers (and LLMs) love

Overview

When to Use

Basic Configuration

Complete Example

Key Options

Data Format

Advanced Features

Migration Flow with Varying Width

Flight Routes Network

Polyline Route with Waypoints

Network Connections on Cartesian

Bidirectional Flow

Performance Tips

Common Use Cases

Migration Map

Flight Routes

Network Topology

Source Reference