sparklinekit/line

SVG and PNG line sparklines.

import sparklinekit/line
import sparklinekit/theme

pub fn small_chart() -> String {
  line.new([1.0, 5.0, 3.0, 8.0, 4.0])
  |> line.with_theme(theme.ocean())
  |> line.with_area_fill(True)
  |> line.to_svg
}

The same Builder value can be rendered to either SVG (to_svg) or PNG (to_png). The SVG output is a self-contained <svg> element string with preserveAspectRatio="none"; the PNG output is a BitArray ready for simplifile.write_bits or bit_array.base64_encode.

Types

Builder

opaque </>

Opaque builder for a line sparkline. Fields are deliberately hidden so renderer-internal state (the theme reference, the area mode, …) can change between minor versions without breaking callers.

pub opaque type Builder

Values

new

</>

pub fn new(values: List(Float)) -> Builder

Start a new line sparkline builder from a list of floats.

Defaults: 240x60 viewBox, currentColor stroke (inherits the surrounding CSS colour), 2.0 stroke width, no background fill, no area fill, no smoothing, no end-point spot.

new_ints

</>

pub fn new_ints(values: List(Int)) -> Builder

Start a builder from a list of Int values. Equivalent to new(list.map(values, int.to_float)), exposed so the call site stays free of integer-to-float adapters.

to_png

</>

pub fn to_png(builder: Builder) -> BitArray

Render the builder to PNG bytes (8-bit RGBA truecolor).

with_size doubles as the pixel size for PNG — a 240x60 builder produces a 240x60 image. The canvas starts at the background colour (transparent when background == "none") and the stroke is drawn with Xiaolin Wu anti-aliasing.

The PNG IDAT payload is written using DEFLATE’s uncompressed “store” blocks (no Huffman coding) so the encoder stays pure Gleam with zero FFI. As a result the output is roughly width * height * 4 bytes regardless of how uniform the image is — for visual size context, prefer SVG.

to_svg

</>

pub fn to_svg(builder: Builder) -> String

Render the builder to a self-contained <svg> element string.

The <svg> carries width, height, and viewBox attributes so the chart sizes itself correctly both when embedded inside a CSS-sized container and when displayed standalone.

with_area_color

</>

pub fn with_area_color(
  builder: Builder,
  color: String,
) -> Builder

Explicitly set the area-fill colour. Implicitly enables the area fill — pass with_area_fill(False) afterwards to remove it.

with_area_fill

</>

pub fn with_area_fill(builder: Builder, enabled: Bool) -> Builder

Toggle the area fill under the line. When enabled without with_area_color the renderer derives a translucent tint from the stroke colour.

with_background_color

</>

pub fn with_background_color(
  builder: Builder,
  color: String,
) -> Builder

Set the background rectangle colour. "none" disables the background (the SVG omits the <rect> and the PNG canvas stays transparent).

with_color

</>

pub fn with_color(builder: Builder, color: String) -> Builder

Set the stroke colour (any CSS colour string).

The value is attribute-escaped before being written into the SVG; for PNG output it is parsed as #rgb / #rgba / #rrggbb / #rrggbbaa and falls back to the active theme’s foreground if unparseable.

with_gradient_area

</>

pub fn with_gradient_area(
  builder: Builder,
  enabled: Bool,
) -> Builder

Toggle the vertical gradient applied to the area fill. When enabled (the default) the fill fades from the area colour at the top to transparent at the baseline; when disabled the fill is a solid tint.

with_int_values

</>

pub fn with_int_values(
  builder: Builder,
  values: List(Int),
) -> Builder

Replace the data series with a list of Ints.

with_size

</>

pub fn with_size(
  builder: Builder,
  width: Int,
  height: Int,
) -> Builder

Set the viewBox / pixel dimensions.

Non-positive values are normalised to 1 so the SVG / PNG stays valid.

with_smoothing

</>

pub fn with_smoothing(builder: Builder, factor: Float) -> Builder

Smooth the polyline into a cubic Bézier curve. factor controls how round the corners get — 0.0 keeps sharp polylines, 0.25 matches the default in react-sparklines, and 0.5 is the roundest reasonable setting. Values outside [0.0, 0.5] are clamped to that range.

with_spot

</>

pub fn with_spot(builder: Builder, radius: Float) -> Builder

Draw a filled circle at the last data point. radius of 0.0 turns the spot off (the default).

with_spot_color

</>

pub fn with_spot_color(
  builder: Builder,
  color: String,
) -> Builder

Override the colour used for the spot. Defaults to the stroke colour (or, if a theme is active, the theme’s foreground).

with_stroke_width

</>

pub fn with_stroke_width(
  builder: Builder,
  stroke_width: Float,
) -> Builder

Set the stroke width in user units. Non-positive values fall back to a hairline (0.5).

with_theme

</>

pub fn with_theme(
  builder: Builder,
  theme: theme.Theme,
) -> Builder

Apply every colour slot from theme. Subsequent with_color / with_background_color / with_area_color calls override one slot at a time.

with_values

</>

pub fn with_values(
  builder: Builder,
  values: List(Float),
) -> Builder

Replace the data series after construction. Useful when the chart’s styling is shared between multiple data sets.