Start with the question the chart must answer, then choose the simplest form that makes the comparison visible. Each example link shows runnable source and rendered output; each API link gives the exact parameters and constraints.

If terms such as mark, encoding, or domain are unfamiliar, see the Glossary. Which Theme flags and Plot settings each mark honors – tooltips, data labels, horizontal orientation, annotations, log scales, color and size channels – is on Feature support.

If one convenience function describes the result, use it. Reach for Plot() when you need layers, facets, or additional encodings. Both approaches return the same Plot type.

Compare categories

Chart	Use it when	Required data	Watch for	Links
Bar	Comparing one value across categories	Category and value columns	A long category list becomes hard to scan; consider horizontal bars	Example · API
Grouped bar	Comparing several series within each category	Categories, series names, and one value list per series	Too many series make each group crowded	Example · API
Lollipop	Showing a light-weight ranking or category comparison	Category and value columns	Thin stems are less effective for precise baseline comparisons than bars	Example · API
Bullet	Comparing actual, target, and qualitative ranges	One row per measure with value, target, and ranges	Best for a small dashboard set, not a long categorical distribution	Example · API
Population pyramid	Comparing two groups across ordered categories	Categories plus left and right value columns	The two sides must use a common scale to support comparison	Example · API
Slope	Comparing two endpoints for each series	Two x positions and paired series values	More than two or three time points usually calls for a line chart	Example · Line API
Bump	Showing rank changes across ordered periods	Periods, series names, and raw values by series	It shows computed rank, not the magnitude behind the rank	Example · API

Show change over time

Chart	Use it when	Required data	Watch for	Links
Line	Showing continuous change or a connected sequence	Numeric x and y columns	Rows connect in input order; sort time data first	Example · API
Step	Showing values that remain constant until the next observation	Numeric x and y columns	Choose the step position to match when a new value takes effect	Example · Line API
Area	Emphasizing magnitude over a continuous baseline	Numeric x and y columns	Filled shapes can hide overlapping series	Example · API
Stepped area	Showing piecewise-constant magnitude over time	Numeric x and y columns	The same step-position semantics as a step line apply	Example · Area API
Stacked area	Showing total and component change together	Ordered categories, series names, and values by series	Middle series have no stable baseline for precise comparison	Example · API
Streamgraph	Showing the changing composition of many series	Ordered categories, series names, and values by series	The centered baseline prioritizes overall shape over exact values	Example · API
Waterfall	Explaining sequential additions and subtractions to a total	Ordered categories and signed deltas	Mark subtotal or total rows explicitly	Example · API
Gantt	Showing scheduled intervals by task	Task names, start values, and end values	Overlapping tasks need ordering chosen before plotting	Example · API
Span	Comparing intervals without implying a project schedule	Categories, starts, and ends	It communicates ranges, not a continuous trajectory	Example · API
Candlestick	Showing open, high, low, and close values by period	Ordered period plus OHLC columns	It is specialized for interval price movement, not general uncertainty	Example · API
Calendar heatmap	Finding daily patterns across weeks and months	Dates and one value per date	Color is less precise than position; label or annotate critical values	Example · API

Show distributions

Chart	Use it when	Required data	Watch for	Links
Histogram	Seeing the shape of one numeric distribution	Raw numeric observations	The bin rule can change the apparent shape	Example · API
Shared-bin histograms	Comparing distributions on identical intervals	Several samples and common bin edges	Separate bins make panels look comparable when they are not	Example · Binning API
Automatic-bin histogram	Choosing a data-dependent starting bin count	Raw numeric observations and a bin rule	Treat the automatic choice as a starting point, not a universal optimum	Example · Bin rules
Box plot	Comparing median, spread, and outliers across groups	Categories and one raw-value list per category	Multimodal distributions can look deceptively similar	Example · API
Violin	Comparing full density shapes across groups	Categories and one raw-value list per category	Density depends on bandwidth and is less stable for small samples	Example · API
Beeswarm	Showing every observation while separating overlaps	Categories and one raw-value list per category	Large samples become dense and expensive to lay out	Example · API
Ridgeline	Comparing many distribution shapes compactly	Categories and one raw-value list per category	Overlap and independent density scaling can hinder magnitude comparison	Example · API
Density curve	Showing a smoothed distribution	Raw numeric observations	Bandwidth controls how much structure is smoothed away	Example · API
Rug	Showing exact observation positions beneath another distribution view	Raw numeric observations	A rug alone becomes unreadable with many repeated or dense values	Example · API
ECDF	Comparing cumulative proportions without choosing bins	Raw numeric observations	It emphasizes ranks and thresholds rather than local density	Example · API
Event plot	Comparing event positions across labeled rows	Row labels and one position list per row	It shows occurrence, not duration or magnitude	Example · API

Show relationships and many variables

Chart	Use it when	Required data	Watch for	Links
Scatter	Seeing association, clusters, and outliers between two variables	Numeric x and y columns	Overplotting can hide density	Example · API
Effect scatter	Emphasizing points with a halo or visual effect	Numeric x and y columns	Decoration should not substitute for an actual data encoding	Example · API
Single axis	Showing values along one numeric dimension	One numeric position per observation	Coincident values overlap without another distinguishing channel	Example · API
Correlation plot	Scanning pairwise correlations across variables	Variable names and a square correlation matrix	Correlation does not establish causation or expose nonlinear structure	Example · API
Parallel coordinates	Comparing observations across many numeric dimensions	One value list per observation and dimension names	Axis order and scaling strongly affect visible patterns	Example · API
Radar	Comparing a few named profiles across common indicators	Indicators, maxima, series names, and values by series	Area and angle make precise cross-axis comparisons difficult	Example · API
Polar line	Showing a relationship naturally expressed as angle and radius	Angle and radius columns	Cartesian alternatives are usually easier to read without a circular domain	Example · API
Multi-series polar	Comparing several angle-radius paths	Angles, series names, and radius values by series	Multiple paths can overlap heavily	Example · API
Wind barbs	Showing vector direction and magnitude at positions	x and y positions plus u and v vector components	Dense fields need enough canvas space to keep glyphs distinct	Example · API

Show composition and progress

Chart	Use it when	Required data	Watch for	Links
Stacked bar	Comparing category totals and their components	Categories, series names, and one value list per series	Interior segments are difficult to compare across bars	Example · API
Pie or donut	Showing a small number of parts of one whole	Categories and non-negative values	Angles are hard to compare; avoid many similar slices	Example · API
Marimekko	Showing two categorical proportions at once	Categories, subcategories, and a subcategory-by-category matrix	Both width and height vary, making exact comparison difficult	Example · API
Funnel	Showing values across ordered process stages	Stage names and non-negative values	Width implies magnitude, not causal conversion between stages	Example · API
Gauge	Showing one value against a bounded target range	Value plus minimum and maximum	Space-inefficient for comparing many values	Example · API
Nightingale rose	Comparing magnitudes around a categorical circle	Categories and non-negative values	Radius can exaggerate area unless the intended scaling is clear	Example · API
Polar bar	Comparing bars along an angular axis	Categories and non-negative values	Circular position makes ordinary category comparison harder	Example · API
Radial bar	Showing category progress around a circle	Categories and non-negative values	A linear bar is more precise when radial layout adds no meaning	Example · API

Show hierarchies

All three hierarchy charts use flattened ids, parent_ids, and leaf values. Exactly one row is the root.

Chart	Use it when	Watch for	Links
Tree	Emphasizing parent-child structure	Deep or broad trees need substantial space	Example · API
Treemap	Comparing leaf size within a hierarchy	Small rectangles leave little room for labels	Example · API
Sunburst	Showing hierarchy depth and part-to-whole size together	Outer arcs are harder to compare and label	Example · API

Show flows and networks

These charts use parallel source, destination, and non-negative value columns.

Chart	Use it when	Watch for	Links
Sankey	Tracing quantities through directed stages	The graph must be acyclic; crossing flows quickly add clutter	Example · API
Chord	Showing weighted connections among a moderate set of entities	Direction and exact values are difficult to compare in a dense circle	Example · API
Arc diagram	Showing connections while preserving a meaningful node order	Long arcs can obscure local structure	Example · API
Graph	Showing general relationships among nodes	The circular layout is deterministic but does not discover communities	Example · API

Show grids, matrices, and fields

Chart	Use it when	Required data	Watch for	Links
Heatmap	Comparing values across two categorical dimensions	Long-form x, y, and value columns	Color supports pattern finding better than exact lookup	Example · API
Image	Displaying a regular row-major numeric array	A rectangular z[row][column] matrix	Row zero appears at the top; size the plot deliberately when aspect matters	Example · API
Pseudocolor mesh	Displaying a matrix over unequal cell boundaries	x edges, y edges, and a rectangular matrix	Each edge list has one more entry than its matrix dimension	Example · API
Contour or filled contour	Showing levels across a regular sampled surface	x coordinates, y coordinates, and a rectangular grid	At least a 2-by-2 grid is required; level choices affect the story	Line example · Filled example · Line API · Filled API
Scattered contour	Estimating levels from irregularly positioned samples	x, y, values, and triangulation-compatible points	Sparse or poorly distributed points can create misleading triangles	Line example · Filled example · Line API · Filled API
Triangular mesh	Inspecting or coloring an irregular triangulation	Point x/y coordinates and, for color, one value per point	The Delaunay mesh quality depends on the point distribution	Mesh example · Color example · Mesh API · Color API
Punchcard	Comparing activity across two categorical cycles	Two categorical columns and values	Large category products produce many small cells	Example · API

Show three dimensions

Reach for these last. A projection collapses three dimensions onto two, so two points that look adjacent may be far apart along the view direction, and every solid hides whatever stands behind it. When the question is about two variables, or about reading a value, a 2D chart above answers it exactly; these answer “what does the whole field look like”.

Chart	Use it when	Required data	Watch for	Links
3D scatter	Looking for clusters or a trend that needs all three variables at once	Equal-length x, y, and z columns	Depth is lost to the view; rotate elev/azim and compare before trusting an apparent cluster	Example · API
3D line	Following one path through space in order	Ordered x, y, and z columns	Segments draw in data order, not depth order, so a later segment covers an earlier one it passes behind	Example · API
Surface or wireframe	Showing the shape of a height field – ridges, saddles, where it falls away	A rectangular z[row][col] grid, optional x and y coordinates	Reads values worse than a contour or heatmap of the same grid; the wireframe keeps the far side visible but turns dense grids into a thicket	Surface example · Wireframe example · Surface API · Wireframe API
Triangulated surface	The same, from samples that do not sit on a grid	Scattered x, y, and one z per point	Fills across the convex hull, so a concave sampled region gets bridged; one z per (x, y) means no overhangs	Example · API
3D bars	Comparing a value over two axes when the shape of the field matters more than any one value	Bar centers x and y with heights z	Every bar hides the ones behind it; a heatmap of the same values hides nothing	Example · API
Voxels	Displaying a blocky solid – an occupancy grid, a segmentation	filled[layer][row][col] booleans	Only the surface is visible; structure inside the solid needs slices, not this	Example · API
3D stems	Reading heights at scattered positions, each tethered to the plane	Equal-length x, y, and z columns	Stems always rise from zero; crossing stems cross visibly whichever was drawn last	Example · API
3D arrows	Sampling a vector field at points	Positions x, y, z and components u, v, w	Heads are sized on the page and never foreshorten, so an arrow pointing at the reader keeps a full head on no shaft	Example · API
3D ribbon	Showing the gap between two curves through space	Two curves with the same number of samples	Where the curves cross, the ribbon pinches; there is no correct draw order at a fold	Example · API

When several charts could work, build the simplest two with the same data and compare what becomes easiest to see. The Examples gallery provides the fastest side-by-side source and output reference.

← Data shapes · Browse Examples →