High-level Express-style API. Accepts Explorer DataFrames or plain lists of
atom- or string-keyed maps (e.g. [%{col: value}] or [%{"col" => value}]).
Returns a Plotly.Figure ready to pipe into Plotly.show/1.
Express-level options
These options are consumed by Plotly.Express before the trace is built.
Everything else is forwarded to the underlying trace struct as-is.
:color— group rows by a column value; each unique value becomes a separate trace. Supported byscatter/2,bar/2,line/2, andquiver/2.:title— setslayout.title:width,:height— setlayout.width/layout.height(pixels):template— setslayout.template(bundled template name or inline map, e.g."plotly_dark","plotly_white","ggplot2")
Data shapes accepted
List of string-keyed maps — most common:
data = [
%{"month" => "Jan", "sales" => 42},
%{"month" => "Feb", "sales" => 55}
]
Plotly.Express.bar(data, x: "month", y: "sales", title: "Revenue")
|> Plotly.show()Column selectors may be atoms or strings. For map rows an exact key wins,
including when its value is nil or false; otherwise the other key form
is used. Missing columns return nil, without creating atoms.
Explorer DataFrame — requires {:explorer, "~> 0.11"} in deps:
df = Explorer.DataFrame.from_csv!("data.csv")
Plotly.Express.scatter(df, x: "date", y: "price")
|> Plotly.show()Summary
Functions
Bar chart.
Polar bar chart.
Box plot.
Candlestick chart.
Choropleth map.
Funnel chart.
2D histogram (density heatmap).
Histogram.
Indicator / gauge chart.
Line chart.
OHLC chart.
Pie chart.
Vector field arrows from positions and vector components.
3D scatter chart.
Scatter chart.
Geographic scatter chart (geo projection).
Tile map scatter (uses open-street-map by default, no API key needed).
Polar scatter chart.
Sunburst chart.
Treemap chart.
Violin plot.
Waterfall chart.
Functions
Bar chart.
Required: :x, :y. Optional: :color (grouped bars — one trace per group),
:title, :width, :height, :template.
Examples
monthly = [
%{"month" => "Jan", "sales" => 1200},
%{"month" => "Feb", "sales" => 1450},
%{"month" => "Mar", "sales" => 1100}
]
Plotly.Express.bar(monthly, x: "month", y: "sales", title: "Monthly Sales")
|> Plotly.show()
# Grouped bar chart — one bar series per region
Plotly.Express.bar(regional_data, x: "quarter", y: "revenue", color: "region")
|> Plotly.show()
iex> data = [%{"x" => "A", "y" => 1, "g" => "r"}, %{"x" => "B", "y" => 2, "g" => "b"}]; :ok
:ok
iex> fig = Plotly.Express.bar(data, x: "x", y: "y", color: "g"); :ok
:ok
iex> length(fig.data)
2Polar bar chart.
Required: :r, :theta. Optional: :title, :width, :height.
Examples
Plotly.Express.barpolar(wind_data, r: "frequency", theta: "direction")
|> Plotly.show()Box plot.
Required: :x, :y. Optional: :title, :width, :height, :template.
Examples
Plotly.Express.box(results, x: "group", y: "value", title: "Distribution by Group")
|> Plotly.show()Candlestick chart.
Required: :x, :open, :high, :low, :close.
Optional: :title, :width, :height.
Examples
prices = [
%{"date" => "2024-01-01", "o" => 150, "h" => 158, "l" => 148, "c" => 155},
%{"date" => "2024-01-02", "o" => 155, "h" => 162, "l" => 153, "c" => 160}
]
Plotly.Express.candlestick(prices,
x: "date", open: "o", high: "h", low: "l", close: "c",
title: "AAPL Jan 2024"
)
|> Plotly.show()Choropleth map.
Required: :locations, :z. Defaults locationmode to "ISO-3".
Optional: :title, :width, :height.
Examples
gdp = [
%{"iso" => "USA", "gdp" => 23_000},
%{"iso" => "DEU", "gdp" => 4_200},
%{"iso" => "CHN", "gdp" => 18_000}
]
Plotly.Express.choropleth(gdp, locations: "iso", z: "gdp", title: "GDP by Country")
|> Plotly.show()Funnel chart.
Required: :x, :y. Optional: :title, :width, :height.
Examples
funnel_data = [
%{"stage" => "Leads", "count" => 1000},
%{"stage" => "Qualified", "count" => 400},
%{"stage" => "Proposals", "count" => 150},
%{"stage" => "Closed", "count" => 60}
]
Plotly.Express.funnel(funnel_data, x: "count", y: "stage", title: "Sales Funnel")
|> Plotly.show()2D histogram (density heatmap).
Required: :x, :y. Optional: :title, :width, :height.
Examples
Plotly.Express.histogram2d(measurements, x: "height", y: "weight",
title: "Height vs Weight Density"
)
|> Plotly.show()Histogram.
Required: :x. Optional: :title, :width, :height, :template.
Examples
data = Enum.map(1..500, fn _ -> %{"score" => :rand.normal(70.0, 10.0)} end)
Plotly.Express.histogram(data, x: "score", title: "Score Distribution")
|> Plotly.show()Indicator / gauge chart.
Required: :value (first row's value is used).
Optional: :title, :width, :height.
Examples
Plotly.Express.indicator([%{"kpi" => 92.5}], value: "kpi", title: "Satisfaction Score")
|> Plotly.show()Line chart.
Required: :x, :y. Optional: :color, :title, :width, :height, :template.
Examples
Plotly.Express.line(time_series, x: "date", y: "value", title: "Trend")
|> Plotly.show()
# Multiple lines via color grouping
Plotly.Express.line(multi_series, x: "date", y: "value", color: "series")
|> Plotly.show()OHLC chart.
Required: :x, :open, :high, :low, :close.
Optional: :title, :width, :height.
Examples
Plotly.Express.ohlc(prices,
x: "date", open: "open", high: "high", low: "low", close: "close"
)
|> Plotly.show()Pie chart.
Required: :values. Optional: :names, :title, :width, :height.
Examples
browser_share = [
%{"browser" => "Chrome", "pct" => 65},
%{"browser" => "Firefox", "pct" => 18},
%{"browser" => "Safari", "pct" => 12},
%{"browser" => "Other", "pct" => 5}
]
Plotly.Express.pie(browser_share,
values: "pct", names: "browser", title: "Browser Market Share"
)
|> Plotly.show()
iex> data = [%{"v" => 10}, %{"v" => 20}]; :ok
:ok
iex> fig = Plotly.Express.pie(data, values: "v"); :ok
:ok
iex> hd(fig.data).values
[10, 20]Vector field arrows from positions and vector components.
Required column selectors: :x, :y, :u, :v.
Optional: :color (one trace per group), :title, :width, :height, :template.
Remaining options, such as :anchor and :lengthfactor, go to each quiver trace.
Examples
iex> field = [%{"x" => 0, "y" => 0, "u" => 1, "v" => 2}]; :ok
:ok
iex> fig = Plotly.Express.quiver(field, x: "x", y: "y", u: "u", v: "v"); :ok
:ok
iex> hd(fig.data).u
[1]3D scatter chart.
Required: :x, :y, :z. Optional: :title, :width, :height, :template.
Examples
points = [
%{"x" => 1, "y" => 2, "z" => 3},
%{"x" => 4, "y" => 5, "z" => 6},
%{"x" => 7, "y" => 8, "z" => 9}
]
Plotly.Express.scatter3d(points, x: "x", y: "y", z: "z", title: "3D Scatter")
|> Plotly.show()Scatter chart.
Required: :x, :y. Optional: :color, :title, :width, :height, :template.
Examples
data = [
%{"year" => 2020, "sales" => 120},
%{"year" => 2021, "sales" => 145},
%{"year" => 2022, "sales" => 180}
]
Plotly.Express.scatter(data, x: "year", y: "sales", title: "Annual Sales")
|> Plotly.show()
# :color groups rows into separate traces — one per unique value
Plotly.Express.scatter(market_data, x: "date", y: "close", color: "ticker")
|> Plotly.show()
iex> data = [%{"a" => 1, "b" => 2}, %{"a" => 3, "b" => 4}]; :ok
:ok
iex> fig = Plotly.Express.scatter(data, x: "a", y: "b"); :ok
:ok
iex> hd(fig.data).x
[1, 3]Geographic scatter chart (geo projection).
Required: :lat, :lon. Optional: :title, :width, :height.
Examples
cities = [
%{"city" => "London", "lat" => 51.5, "lon" => -0.1, "pop" => 9_000_000},
%{"city" => "Tokyo", "lat" => 35.7, "lon" => 139.7, "pop" => 14_000_000}
]
Plotly.Express.scattergeo(cities, lat: "lat", lon: "lon", title: "World Cities")
|> Plotly.show()Tile map scatter (uses open-street-map by default, no API key needed).
Required: :lat, :lon. Optional: :title, :width, :height.
Examples
stations = [
%{"name" => "London", "lat" => 51.5074, "lon" => -0.1278},
%{"name" => "Paris", "lat" => 48.8566, "lon" => 2.3522},
%{"name" => "Berlin", "lat" => 52.5200, "lon" => 13.4050}
]
Plotly.Express.scattermap(stations, lat: "lat", lon: "lon", title: "European Capitals")
|> Plotly.show()Polar scatter chart.
Required: :r, :theta. Optional: :title, :width, :height.
Examples
wind = Enum.map(0..11, fn i -> %{"deg" => i * 30, "speed" => :rand.uniform(20)} end)
Plotly.Express.scatterpolar(wind, r: "speed", theta: "deg", title: "Wind Rose")
|> Plotly.show()Sunburst chart.
Required: :labels, :parents. Optional: :values, :title, :width, :height.
Examples
hierarchy = [
%{"id" => "World", "parent" => "", "pop" => 8_000},
%{"id" => "Asia", "parent" => "World", "pop" => 4_600},
%{"id" => "Europe", "parent" => "World", "pop" => 750}
]
Plotly.Express.sunburst(hierarchy,
labels: "id", parents: "parent", values: "pop", title: "Population by Region"
)
|> Plotly.show()Treemap chart.
Required: :labels, :parents. Optional: :values, :title, :width, :height.
Examples
Plotly.Express.treemap(hierarchy, labels: "id", parents: "parent", values: "size")
|> Plotly.show()Violin plot.
Required: :x, :y. Optional: :title, :width, :height, :template.
Examples
Plotly.Express.violin(measurements, x: "category", y: "value", title: "Distribution")
|> Plotly.show()Waterfall chart.
Required: :x, :y. Optional: :title, :width, :height.
Examples
cashflow = [
%{"item" => "Revenue", "amount" => 500},
%{"item" => "COGS", "amount" => -200},
%{"item" => "Gross Profit", "amount" => 300}
]
Plotly.Express.waterfall(cashflow, x: "item", y: "amount", title: "P&L Waterfall")
|> Plotly.show()