# ggsvelte > A layered grammar of graphics for JavaScript: ggplot2 semantics (aes/geom/stat/scale/coord/facet/theme/position), a strictly-JSON PortableSpec that agents emit (published JSON Schema for constrained decoding), a fluent builder, Svelte 5 components, hybrid SVG/canvas rendering, and value-stable color scales. validate() returns { code, path, message, fix } errors whose fix.example is machine-applicable. ## Current release facts - Package version: 0.37.0 - Defaults edition: 2 - Registered chart themes (33): default, light, dark, minimal, ggplot2, classic, bw, hrbr, few, clean, fivethirtyeight, economist, tufte, linedraw, void, stata, stata_s1color, solarized, solarizeddark, economist_white, solarized_2, solarized_2dark, wsj, hc, hcdark, pander, base, igray, map, solid, grey, gray, test ## Docs - [Getting started](https://ggsvelte.sh/guide/getting-started): Install @ggsvelte/svelte and render one chart from a Svelte file. - [Statistics and positions](https://ggsvelte.sh/guide/statistics-positions): Compute summaries and control how derived marks occupy the same coordinate space. - [Scales and guides](https://ggsvelte.sh/guide/scales-guides): Translate data domains into position, color, labels, axes, and legends. - [Facets and coordinates](https://ggsvelte.sh/guide/facets-coordinates): Repeat one grammar across panels and choose how axes compose the view. - [Dates without preprocessing](https://ggsvelte.sh/guide/temporal-scales): Value-driven date inference, strict parsers, overrides, and diagnostics. - [Interactions](https://ggsvelte.sh/guide/interactions): Inspection, selection, zoom, keyboard behavior, identity, and event contracts. - [Production](https://ggsvelte.sh/guide/production): Responsive sizing, SVG/canvas rendering, SSR and export, and tested runtime support. - [Interaction reference](https://ggsvelte.sh/guide/interaction-reference): Search interaction props, callbacks, event phases, and diagnostic codes. - [Errors reference](https://ggsvelte.sh/guide/errors): Understand validation, render, interaction, and CLI diagnostics and recover safely. - [Advisories](https://ggsvelte.sh/guide/advisories): Spec-lint advisories and the pipeline's disclosed heuristics. - [Lifecycle & editions](https://ggsvelte.sh/guide/lifecycle): API stability tags per export, and the defaults-edition mechanism. - [Upgrade guide](https://ggsvelte.sh/guide/upgrading): Check versions, apply fixture-backed changes, and verify each 0.x transition. - [Geoms](https://ggsvelte.sh/reference/geoms): every Geom* component with defaults, allowed stats/positions, and params from the schema - [Stats](https://ggsvelte.sh/reference/stats): every statistical transform with after_stat columns and compatible geoms - [Positions](https://ggsvelte.sh/reference/positions): every position adjustment with positionParams and compatible geoms - [Scales](https://ggsvelte.sh/reference/scales): every Scale* component for position, color/fill, and style channels - [Guides and legends](https://ggsvelte.sh/reference/guides): GuideLegend, GuideColorbar, GuideColorsteps, GuideAxis, and GuideNone with channels and props - [Labs](https://ggsvelte.sh/reference/labs): plot title, subtitle, caption, and per-aesthetic axis/legend titles - [Axes and ticks](https://ggsvelte.sh/reference/axes): GuideAxis presentation, scale breaks/labels, band layout, and grids - [Labels](https://ggsvelte.sh/reference/labels): plot chrome vs tick labels vs GeomText/GeomLabel/SF data labels - [Search interaction reference](https://ggsvelte.sh/reference/interactions): filter interaction capabilities, events, diagnostics, and accessibility guidance - [JSON Schema v0](https://ggsvelte.sh/schema/v0.json): the PortableSpec schema (unstable in v0.1) - [llms-full.txt](https://ggsvelte.sh/llms-full.txt): all docs prose plus every example (spec JSON + Svelte source) ## Examples ### Areas - [Survivors from a cohort of one thousand](https://ggsvelte.sh/examples/area/basic): A single series drawn as a filled area under the curve. Use this when the area itself carries the quantity. - [Stacked deaths by cause over time](https://ggsvelte.sh/examples/area/stacked): Stacked areas for parts of a whole that change over time. ### Bars & columns - [US beer production by package type](https://ggsvelte.sh/examples/bar/dodged): Dodged bars of national production by year and package. - [Category totals, flipped so labels read across](https://ggsvelte.sh/examples/bar/horizontal): Horizontal bars when category labels are long and the ranking matters. - [Parts of a whole within each group](https://ggsvelte.sh/examples/bar/proportions): Bars stacked to a full height so each segment reads as a share of its group. - [Stacked counts inside each bag](https://ggsvelte.sh/examples/bar/stacked): Stacked bars when you need counts and composition in the same mark. ### Distributions - [Two-dimensional bins for a dense cloud](https://ggsvelte.sh/examples/bin2d/basic): 2D bins when a scatter is too dense for individual points. ### Annotations & rules - [Axes without marks](https://ggsvelte.sh/examples/blank/axes-only): Blank axes when you need the trained domain without a geom. - [Expanded domain with no marks](https://ggsvelte.sh/examples/blank/domain-expand): Domain expansion when a reference value must stay inside the plot area. ### Distributions - [Boxplots for five runs of the same experiment](https://ggsvelte.sh/examples/boxplot/by-category): Category boxplots for comparing distributions side by side. ### Boxes & distributions - [Violin plots for the same five runs](https://ggsvelte.sh/examples/boxplot/violin): Violins when the full shape of each group matters more than the five-number summary alone. ### Bars & columns - [Counts across ordered chest sizes](https://ggsvelte.sh/examples/col/basic): Simple columns for discrete counts along one ordered axis. - [Long category labels at a narrow width](https://ggsvelte.sh/examples/col/long-labels): A layout specimen: Spanish multi-word names and a long German compound at about 480px, where the band axis has to wrap and rotate to fit. - [One long label among short ones](https://ggsvelte.sh/examples/col/mixed-outlier-labels): A layout specimen: short categories with a single four-word outlier at a normal desktop width, where the axis should wrap rather than rotate everything. - [Linedraw theme on chest-size columns](https://ggsvelte.sh/examples/col/theme-linedraw): Linedraw theme on ordered chest counts: hard black axes and grid on white, with no grey chrome. - [Columns with the rate printed on each bar](https://ggsvelte.sh/examples/col/value-labels): Value labels when the exact number is the point of the chart. ### Color & legends - [How many items you can tell apart at once](https://ggsvelte.sh/examples/color/binned): Binned continuous colour when discrete steps read clearer than a smooth ramp. ### Surfaces & grids - [Contours of height on a grid](https://ggsvelte.sh/examples/contour/basic): Contours when the input is a continuous surface on a grid. ### Statistical summaries - [Interval boxes with mid line](https://ggsvelte.sh/examples/crossbar/boxes): Three tall identity boxes with a mid horizontal line — crossbar's mark shape at index thumbnail size. ### Lines & rules - [Paired points joined by a curve](https://ggsvelte.sh/examples/curve/connectors): Curved connectors when straight segments would crowd and you want origin→end pairs. ### Distributions - [2D density isolines](https://ggsvelte.sh/examples/density/kde-2d): Kernel density drawn as contour lines over 578 point locations. The rings tighten where the points cluster — here, the streets around one pump on Snow's 1854 Soho map. ### Statistical summaries - [Filled 2D density bands](https://ggsvelte.sh/examples/density/kde-2d-filled): Kernel density drawn as shaded rings over 578 point locations. Darker bands sit where the points are densest — here, the streets around one pump on Snow's 1854 Soho map. ### Distributions - [Two densities on one axis](https://ggsvelte.sh/examples/density/overlay): Overlapping density curves for comparing continuous distributions. - [One dot per measurement, stacked in bins](https://ggsvelte.sh/examples/dotplot/histodot): Dotplots when the sample is small enough that every observation should stay visible. ### Statistical summaries - [Capped error bars](https://ggsvelte.sh/examples/errorbar/caps): Three tall identity intervals with end caps — the mark shape that reads at index thumbnail size. - [Mean and standard error by group](https://ggsvelte.sh/examples/errorbar/mean-se): Mean ± SE for a control and three hypnotic treatments. - [Mean and standard error in each x class](https://ggsvelte.sh/examples/errorbar/summary-bin): Summary error bars after binning x when you need mean and uncertainty together. ### Facets - [Facets with ordered side strips](https://ggsvelte.sh/examples/facet/ordered-side-strips): Facet strips ordered to match the sample order of the experiment. - [One panel per parent–child pair type](https://ggsvelte.sh/examples/facet/wrap): Facet wrap when a grouping field should become a grid of small multiples. - [Facets with free y scales](https://ggsvelte.sh/examples/facet/wrap-free-y): Free y scales when panels share an x axis but live on different magnitudes. ### Distributions - [Frequency polygon through bin centres](https://ggsvelte.sh/examples/freqpoly/basic): Frequency polygons when you want a histogram's bins without the solid bars. - [Hex bins for a dense cloud](https://ggsvelte.sh/examples/hex/basic): Hex bins as an alternative to rectangular 2D bins. - [Histogram of a hundred experimental runs](https://ggsvelte.sh/examples/histogram/basic): A basic histogram for a single continuous measurement. ### Annotations & rules - [One horizontal threshold](https://ggsvelte.sh/examples/hline/threshold): Horizontal rules for thresholds, targets, or known reference values across a panel. ### Interaction - [Interval selection and zoom](https://ggsvelte.sh/examples/interaction/brush-zoom): 333 Palmer penguins: brush a rectangle to select, or zoom into the crowded middle where the species overlap. - [One interval, applied in every panel](https://ggsvelte.sh/examples/interaction/facet-intervals): 333 Palmer penguins split by island, with a coordinate interval selection that holds across all the facets at once. - [Filter series from the legend](https://ggsvelte.sh/examples/interaction/legend-filter): Legend filter when readers need to hide series without losing colour identity. - [Focus a legend group without changing the data](https://ggsvelte.sh/examples/interaction/legend-focus): Three of Playfair's commodity series. Focusing a group dims the others rather than dropping them, so the scales never move under you. - [Link plots, controls, and a table](https://ggsvelte.sh/examples/interaction/linked-views): Five Palmer penguins per species, so every row a selection touches is visible in the table beside the chart. - [Inspect and pin data](https://ggsvelte.sh/examples/interaction/tooltip): Palmer penguin measurements with a crosshair that reads every series at one x, and a pin so the reading stays while you look elsewhere. ### Points & scatter - [Menu calories, spread so items do not stack](https://ggsvelte.sh/examples/jitter/basic): Jittered entrée calories by restaurant. Use this when many points share a category and would otherwise cover each other. - [Jittered points by group](https://ggsvelte.sh/examples/jitter/spread): Twelve large points in three columns with wide horizontal jitter — the alias mark that reads at index thumbnail size. ### Labels & text - [Boxed labels](https://ggsvelte.sh/examples/label/basic): A few large rounded boxes behind short names so GeomLabel reads at index thumbnail size. ### Lines & time - [Empirical distribution of event sizes](https://ggsvelte.sh/examples/line/ecdf): ECDF lines for the cumulative share of observations at or below each value. ### Lines & rules - [Observed counts against a fitted curve](https://ggsvelte.sh/examples/line/function): Function lines when theory (or a fit) should sit on top of the data. ### Lines & time - [Weeks of work for a quarter of wheat](https://ggsvelte.sh/examples/line/labor-cost-of-wheat): Playfair's purchasing-power argument as a single series: wheat price divided by a mechanic's weekly wage. A quarter is about eight bushels of grain — lower is cheaper grain in labor terms. - [Wheat price and a mechanic's weekly wage](https://ggsvelte.sh/examples/line/multi-series): Playfair's 1821 levels chart: the price of one quarter of wheat (~8 bushels) and a good mechanic's weekly pay, both in shillings. Same currency, different baskets — he wanted you to eye the ratio, not add the series. - [Years inferred from raw four-digit strings](https://ggsvelte.sh/examples/line/time-axis): Temporal scales from plain year strings when the calendar meaning is obvious. ### Statistical summaries - [Bare vertical stems](https://ggsvelte.sh/examples/linerange/stems): Three tall identity stems without end caps — linerange's mark shape at index thumbnail size. ### Maps & polygons - [Snow's outbreak by nearest pump](https://ggsvelte.sh/examples/map/choropleth): Thirteen Soho neighbourhoods shaded by cholera deaths inside each. One region holds 359 of the 578, around Broad Street. ### Lines & time - [Minard's retreat thermometer](https://ggsvelte.sh/examples/path/connect-hv): Nine temperature readings taken along the road back from Moscow, joined by horizontal-then-vertical elbows so each reading holds until the next one was taken. ### Points & scatter - [Confidence ellipses around groups](https://ggsvelte.sh/examples/path/ellipse-rings): Ellipse rings when each group needs a region of typical bivariate spread. ### Maps & polygons - [Napoleon's march on Moscow, by Minard](https://ggsvelte.sh/examples/path/trajectory): Path map of army strength with a temperature strip. ### Points & scatter - [Points against the identity line](https://ggsvelte.sh/examples/point/abline-identity): Identity ablines when agreement with y = x is the claim. - [Overlapping points sized by how many share a cell](https://ggsvelte.sh/examples/point/count): Count stat on points when discrete rounding collapses many rows onto few coordinates. ### Scatter plots - [Equal data units on both axes](https://ggsvelte.sh/examples/point/fixed-aspect): Fixed aspect when shape in data units must not stretch with the panel. ### Points & scatter - [Many years folded onto one seasonal axis](https://ggsvelte.sh/examples/point/gradient-continuous): Continuous colour gradients when a third continuous channel carries identity. - [Scatter coloured by discrete group](https://ggsvelte.sh/examples/point/hue-discrete): Discrete hue when categories are unordered and equal visual weight matters. - [Calories by restaurant, with jitter](https://ggsvelte.sh/examples/point/jitter): Fast-food menu calories by restaurant. Position jitter spreads marks that would otherwise stack on the same category. ### Scatter plots - [What the wars did to the national debt](https://ggsvelte.sh/examples/point/layer-data-bands): Playfair's debt series with two war periods behind it and one note on top, each layer carrying its own table because only one of the three is a measurement. ### Points & scatter - [Cholera, crowding and water in London, 1849](https://ggsvelte.sh/examples/point/log-scale): Farr's 38 districts: death rate against population density on a log x scale, coloured by which company supplied the water. - [Flavor against aroma in cupping scores](https://ggsvelte.sh/examples/point/quantile-lines): Quantile lines through coffee cupping scores. Use this when a mean smooth hides how the spread of y moves with x. - [Two measures coloured by region](https://ggsvelte.sh/examples/point/scatter-color): Scatter with a discrete colour when geography or group is the third channel. - [Raw points with a manual mean per group](https://ggsvelte.sh/examples/point/stat-manual-mean): Manual summary stats when you want both the cloud and the group mean on one panel. - [Collapse duplicate coordinates to unique marks](https://ggsvelte.sh/examples/point/stat-unique): Unique stat when repeated keys would overplot identical positions. - [Cholera against height above the Thames](https://ggsvelte.sh/examples/point/steps-binned): Farr's 38 London districts of 1849, coloured in bands by their poor rate. A stepped ramp reads as brackets, which is how a rate like this gets argued about. - [A sparkline without axes or grid](https://ggsvelte.sh/examples/point/void-chrome): Void theme when the mark alone is the chart. ### Statistical summaries - [Stem plus mid point](https://ggsvelte.sh/examples/pointrange/midpoints): Three tall identity stems with a large mid point — pointrange's mark shape at index thumbnail size. ### Rectangles & grids - [Which pump was nearest](https://ggsvelte.sh/examples/polygon/regions): The thirteen areas of Soho closest to each public pump in 1854, each drawn as one closed ring of vertices in winding order. ### Distributions - [Sparse Q–Q cloud](https://ggsvelte.sh/examples/qq/cloud): Twelve large sample quantiles vs theoretical normal — the scatter mark that reads at index thumbnail size. - [Sample quantiles against the normal](https://ggsvelte.sh/examples/qq/normal): Normal QQ plots for a quick normality check. - [Q–Q reference line](https://ggsvelte.sh/examples/qq_line/match): Thick line through the sample/theoretical quartile match — the mark that reads at index thumbnail size. ### Rectangles & grids - [Where chocolate reviews cluster](https://ggsvelte.sh/examples/raster/grid): A complete cocoa-percent × rating grid of bar counts. Use a raster when your table is already a regular grid of fill values. - [Background rectangles for eras](https://ggsvelte.sh/examples/rect/regions): Rect regions when historical or policy eras should sit behind a series. ### Areas - [A ribbon for year-to-year range](https://ggsvelte.sh/examples/ribbon/bounds): Ribbons for uncertainty or observed range around a central series. - [A ribbon with gradient fill, stroke and glow](https://ggsvelte.sh/examples/ribbon/paint): The paint options a ribbon can carry, on a precomputed interval: a portable gradient across the band, a stroked edge and a glow beneath. ### Annotations & rules - [Bottom-edge rug ticks](https://ggsvelte.sh/examples/rug/ticks): Ten long thick ticks along the panel bottom — the marginal mark that reads at index thumbnail size. - [A crosshair of two fixed intercepts](https://ggsvelte.sh/examples/rule/annotation): Annotation rules for cutoffs and known constants: one vertical and one horizontal intercept on continuous data. - [A rug of every cupping score](https://ggsvelte.sh/examples/rule/data-driven): One vertical rule per coffee lot on total cup points. Use this when you want a 1-D sample drawn as a strip of marks. ### Lines & rules - [Segments from start to end of each pair](https://ggsvelte.sh/examples/segment/annotations): Segments when each row is a directed change between two points. ### Maps & spatial - [Simple features as filled polygons](https://ggsvelte.sh/examples/sf/basic): Basic sf polygons for map-like regions without a full basemap stack. - [Pump names on measured boxes](https://ggsvelte.sh/examples/sf/boxed-labels): Thirteen Soho neighbourhoods with each pump name on a measured box. The box keeps the name readable over a coloured fill. - [One feature with two separate polygons](https://ggsvelte.sh/examples/sf/geometry-collection): Geometry collections when one logical feature spans disconnected pieces. - [Polygons with holes](https://ggsvelte.sh/examples/sf/holes): Holes when an inner ring should cut out of an outer polygon. - [Snow's pumps, named in place](https://ggsvelte.sh/examples/sf/labels): The thirteen Soho neighbourhoods with each pump's street name set at the centre of the area it served, positioned from the geometry rather than from x and y. ### Showcase - [Kyoto cherry blossoms, 812–2026](https://ggsvelte.sh/examples/showcase/kyoto-sakura): Tufte's full-bloom chart at full fidelity: 30-year rolling median, epoch bands, labeled baseline, and circled records. ### Statistical summaries - [Cocoa percent against bar rating](https://ggsvelte.sh/examples/smooth/loess-scatter): Loess through a sample of chocolate reviews, with a confidence band. Copy this pattern when you want a smooth trend on a dense scatter. ### Lines & rules - [Eight rays from one origin](https://ggsvelte.sh/examples/spoke/rays): Eight long thick spokes at equal angles — the mark shape that reads at index thumbnail size. - [Direction and length from each point](https://ggsvelte.sh/examples/spoke/vector-field): Spokes for vector fields with origin, angle, and radius. ### Lines & time - [Step ECDF of paired differences](https://ggsvelte.sh/examples/step/ecdf): Step ECDFs for cumulative distributions of differences or measurements. - [Thick staircase](https://ggsvelte.sh/examples/step/stairs): Five vertices joined with hv steps — the stair mark that reads at index thumbnail size. ### Labels & text - [Bare text labels](https://ggsvelte.sh/examples/text/labels): A few large bare text marks — short names so the geom reads at index thumbnail size. ### Rectangles & grids - [Cholera in England and Wales, 1849](https://ggsvelte.sh/examples/tile/heatmap): Every day of the epidemic from Farr's weekly returns, laid out as a calendar of square tiles so the summer peak reads as a block. ### Annotations & rules - [One vertical cutoff](https://ggsvelte.sh/examples/vline/cutoff): Vertical rules for cutoffs along a sequence or continuous x across a panel.