Machine-readable page content
Canonical: https://semiotic.nteract.io/interoperability/vega-lite
Vega-Lite Translator
Why
Vega-Lite is the most popular declarative grammar for visualization. Many users have existing Vega-Lite specs from notebooks, dashboards, or AI-generated output. The fromVegaLite() function lets you paste a spec and get a working Semiotic chart instantly.
The function returns a ChartConfig, so it composes withconfigToJSX(), copyConfig(),toURL(), and the rest of the serialization API.
JSX
import { fromVegaLite } from "semiotic/data" import { configToJSX, fromConfig } from "semiotic" const config = fromVegaLite(vegaLiteSpec) // Get JSX code const jsx = configToJSX(config) // Or reconstruct props for rendering const { componentName, props } = fromConfig(config)
Live Translator
Edit the Vega-Lite JSON spec below or load a sample. The translated Semiotic chart and generated JSX update automatically.
Semiotic Output→ BarChart
JSX
<BarChart categoryAccessor="region" valueAccessor="sales" data={[ { "region": "North", "sales": 420 }, { "region": "South", "sales": 380 }, { "region": "East", "sales": 510 }, { "region": "West", "sales": 290 } ]} />
Mark → Component Mapping
| Vega-Lite Mark | Semiotic Component | Condition |
|---|
bar | BarChart | default |
bar + color | StackedBarChart | color encoding present |
line | LineChart | default |
area | AreaChart | default |
area + color | StackedAreaChart | color encoding present |
point / circle / square | Scatterplot | default |
point + size | BubbleChart | size encoding present |
rect | Heatmap | default |
arc | PieChart | default |
arc + innerRadius | DonutChart | innerRadius > 0 |
tick | DotPlot | default |
any + bin | Histogram | bin encoding present |
Encoding → Props Mapping
| Vega-Lite Encoding | Semiotic Prop |
|---|
encoding.x.field | xAccessor / categoryAccessor |
encoding.y.field | yAccessor / valueAccessor |
encoding.color.field | colorBy |
encoding.color.scale.scheme | colorScheme |
encoding.size.field | sizeBy |
encoding.size.scale.range | sizeRange |
encoding.theta.field | valueAccessor (arc) |
encoding.x.axis.title | xLabel / categoryLabel |
encoding.y.axis.title | yLabel / valueLabel |
mark.interpolate | curve |
mark.point | showPoints |
mark.innerRadius | innerRadius |
spec.width | width |
spec.height | height |
spec.title | title |
Aggregation
Encoding aggregates support sum, mean (or average), count, min, and max. All nonaggregated encoding fields remain grouping dimensions, including color and size. Numeric and Date group keys retain their types. Numeric aggregates ignore missing, blank, nonnumeric, and nonfinite measures; an all-missing group has a null result. Count includes every source row. Output accessors use an unused field name so a category or series named value is preserved.
Histograms receive the original observations, including repeated values. Combining binning with an aggregate other than count, or requesting an unsupported aggregate such as median, produces a warning. The experimental unstable_fromVegaLiteResult API refuses these requests in strict mode and reports the loss in lossy mode.
For direct aggregation, rollup from semiotic/dataaccepts a field or an array of fields as groupBy. Its output field defaults to value; set outputFieldwhen that name is already a grouping field. A collision throws an error.
Limitations
- Inline data only —
data.url is not supported. Load your data first, then pass it in the spec asdata.values. - No layers or facets — only single-mark specs are translated. Multi-layer or faceted views are not supported.
- No selections — Vega-Lite selections (
params) are not translated. - Limited transforms — only
aggregateand bin are handled. Other transforms (filter, fold, calculate) should be applied to your data before callingfromVegaLite(). - Core marks only —
geoshape,text, rule, and image marks are not supported.