Charts - Scatter & Bubble

#Usage

import {
    ChartAnnotation,
    ChartCanvas,
    ChartCaption,
    ChartDataLabels,
    ChartDecimation,
    ChartExportMenu,
    ChartHover,
    ChartItem,
    ChartLegend,
    ChartNavigator,
    ChartReferenceBand,
    ChartReferenceLine,
    ChartScatter,
    ChartSvg,
    ChartTitle,
    ChartTooltip,
    ChartXAxis,
    ChartYAxis,
    ChartZoom
} from '@primeui/vue-chart';

<ChartSvg>
    <ChartScatter :data="data" value-x-field="valueXField" value-y-field="valueYField" />
    <ChartXAxis />
    <ChartYAxis />
</ChartSvg>

Scatter charts reveal correlations, clusters, and distributions across two numeric dimensions. Both axes are continuous by default. Add sizeField to encode a third dimension as bubble radius.

#Basic

Set valueXField and valueYField to map numeric data fields. Add ChartXAxis and ChartYAxis to render axes with labels and gridlines.

#Bubble

Set sizeField to a numeric data field to encode a third dimension as bubble radius. Each point's radius scales between minSize and maxSize based on its value. Sizing is area-based, so the perceived bubble size grows in line with the underlying number.

#Colors

Pass a static color, array (cycles by index), field name, or function to color to control point fill. Use a static value for a uniform series color or a callback for per-point coloring based on data.

#Gradient Color

Pass a gradient object to color to apply a gradient fill to every point. Radial gradients are centered at each point and sized to the point radius, which gives bubbles a sense of depth. Linear gradients span the full chart area, the same as bars and lines.

#Markers

Set markerShape to differentiate series visually. The built-in shapes are circle, square, triangle, cross, and star. Use markerSize to control the radius and pointRotation to orient the shape. In bubble mode markerSize is ignored and the radius comes from the size field instead.

#Custom Markers

Set renderMarker to replace built-in shapes with custom content. In SVG mode return a VNode centered at the origin; the chart handles translation to each point's position. In Canvas mode the context is pre-translated to the point, so draw at origin and return null.

#Border

Set pointBorderColor and pointBorderStrokeWidth to add an outline stroke around each marker. A white border helps separate overlapping points and makes multi-series charts easier to read at a glance.

#Declarative

Define data points inline using ChartItem children instead of a data array. Each ChartItem accepts value-x and value-y for coordinates, plus color for per-point color overrides.

#Title & Caption

Add ChartTitle to display a title above the chart and ChartCaption for a descriptive line beneath it. Adding both reduces the available chart area.

For full configuration see Title & Caption.

#Hover

ChartHover brightens the hovered point while the rest stay at normal opacity. Set brightness to control the lightening factor, and set dimOpacity below 1 when you intentionally want non-hovered points to fade. Use hoverPointRadius on ChartScatter to control how much the marker enlarges; the default is markerSize × 1.3.

For full configuration see Hover.

#Tooltip

Add ChartTooltip to show data details on hover. Unlike line charts, scatter tooltip hit-testing uses 2D Euclidean distance. The nearest point within pointHitRadius pixels is highlighted regardless of axis position.

For full configuration see Tooltip.

#Legend

Add ChartLegend to display an interactive legend. Each ChartScatter series appears as a separate entry; click any item to toggle that series.

For full configuration see Legend.

#Axes

Use label on ChartXAxis and ChartYAxis to add axis titles. Set startFromZero to anchor the axis at zero, tickCount to control tick density, and type="logarithmic" for data spanning multiple orders of magnitude.

For full configuration see Axes.

#Data Labels

Add ChartDataLabels to display sparse point labels or values. Set display to value, percentage, both, label, label-percentage, or none.

For full configuration see Data Labels.

#Zoom & Navigator

Add ChartZoom with mode="xy" to zoom both axes at once. Drag a rectangle to select a region. Add ChartNavigator for a mini overview below the chart. This is handy for dense scatter plots where zooming reveals clusters.

For full configuration see Zoom & Pan and Navigator.

#Annotation

Use ChartAnnotation to render custom content overlaid on the chart area. The render callback receives chartArea, center, xScale, yScale, textColor, isDark, and ctx (Canvas mode only). Use xScale and yScale to position annotations at specific data coordinates. Use this for quadrant labels and callouts on extreme points. On multi-axis charts use getScale('y2') to position against a secondary axis by its ID. In SVG mode return a VNode. In Canvas mode draw to ctx and return null.

For full configuration see Annotation.

#Reference Lines & Bands

Add ChartReferenceLine to draw threshold or divider lines. Set both x and y reference lines to divide the chart into quadrants. Setting both creates quadrant divisions for scatter plots. Add ChartReferenceBand to highlight acceptable value ranges.

For full configuration see Reference Lines & Bands.

#Decimation

Add ChartDecimation to downsample large scatter datasets before rendering. Set algorithm to 'lttb' (shape-preserving), 'min-max' (peak-preserving), or 'k-means' (cluster-based, optimized for scatter). Set samples to control the target output point count.

For full configuration see Decimation.

#Animation

Pass the chart-root animation prop (<ChartSvg> / <ChartCanvas>) to control entrance and update transitions. Points fade in on entrance and animate to new positions on data updates.

For full configuration see Animation.

#Export

Add ChartExportMenu to let users download the chart as PNG, SVG, or PDF.

See Export for format options and programmatic export.

#Responsive

See Responsive for container sizing, aspect ratio, and breakpoint configuration.

#Accessibility

See Accessibility for ARIA labels, keyboard navigation, and screen reader support.

#API

#ChartScatter

Visual styling props with type accessor → R accept a static value, a per-item array, a field name (keyof T), or a callback (ctx: ItemContext<T>) => R | undefined. Color-family arrays cycle modulo length; other accessor arrays clip and fall back to the series default.

#PointRenderContext

Passed to the renderMarker callback for each data point.

#ItemContext

Passed to every accessor → R callback. Return undefined to fall back to the series-level default for that item.

#ChartItem

Use ChartItem as children of ChartScatter instead of a data array for inline point definitions.

#Related Docs

• Scatter Examples
• Bubble Examples
• Legend
• Tooltip
• Hover
• Data Labels
• Annotation
• Zoom & Pan
• Navigator
• Reference Lines & Bands
• Animation
• Axes