SparklineSvg is a library to generate SVG sparkline charts.

A sparkline is a small, simple chart that is drawn without axes or coordinates. It presents the general shape of the variation of a dataset at a glance.

SparklineSvg allows you to create a sparkline chart from various data shapes and show the dots, the line, and the area under the line. You can also add markers to the chart to highlight specific spots. You can also show common reference lines.

Usage example

# Datapoints and general options
datapoints = [1, 3, 2, 2, 5]
options = [width: 200, height: 40]

# A very simple line chart
sparkline = SparklineSvg.new(datapoints, options)

# Display what you want
line_options = [width: 0.3, color: "green"]
sparkline = SparklineSvg.show_line(sparkline, line_options)

# Render the chart to an SVG string
{:ok, svg} = SparklineSvg.to_svg(sparkline) # or
svg = SparklineSvg.to_svg!(sparkline)

Datapoints

Datapoints are the values that will be used to draw the chart. They can be:

• A list of numbers, where each number is a value for the y axis. The x axis will be the index of the number in the list.
• A list of tuples with two values. The first value is the x axis and the second value is the y axis. The x value can be a number, a DateTime, a Date, a Time, or a NaiveDateTime. The y value must be a number.

All x values in the list must be of the same type.

Tuple-based datapoints

# Datapoints
datapoints = [{1, 1}, {2, 2}, {3, 3}]
datapoints = [{1.1, 1}, {1.2, 2}, {1.3, 3}]

# Datapoints with DateTime
datapoints = [
  {~U[2021-01-01 00:00:00Z], 1},
  {~U[2021-01-02 00:00:00Z], 2},
  {~U[2021-01-03 00:00:00Z], 3}
]

# Datapoints with Date
datapoints = [{~D[2021-01-01], 1}, {~D[2021-01-02], 2}, {~D[2021-01-03], 3}]

# Datapoints with Time
datapoints = [{~T[00:01:00], 1}, {~T[00:02:00], 2}, {~T[00:03:00], 3}]

# Datapoints with NaiveDateTime
datapoints = [
  {~N[2021-01-01 00:00:00], 1},
  {~N[2021-01-02 00:00:00], 2},
  {~N[2021-01-03 00:00:00], 3}
]

Simple datapoints

# Number datapoints
datapoints = [1, 2, 3]
datapoints = [1.1, 1.2, 1.3]

Markers

Markers are used to highlight specific spots on the chart. They differ from the datapoints and therefore are set separately from it. You can add as many markers as you want to a chart.

There are two types of markers:

• A single marker that will be rendered as a vertical line that span the entire height of the chart.
• A range marker that will be rendered as a rectangle that span the entire height of the chart.

Markers are not used to calculate the boundaries of the chart. If a marker is set outside the range of the chart, it will be rendered but won't be visible.

We always set the x value of the marker (position on the x axis). The marker must be of the same type as the x axis of the chart.

Single marker

svg =
  datapoints
  |> SparklineSvg.new()
  |> SparklineSvg.show_line()
  |> SparklineSvg.add_marker(2)
  |> SparklineSvg.add_marker([3, 4])
  |> SparklineSvg.to_svg!()

Range marker

svg =
  datapoints
  |> SparklineSvg.new()
  |> SparklineSvg.show_line()
  |> SparklineSvg.add_marker({1, 2})
  |> SparklineSvg.add_marker([{3, 4}, {5, 6}])
  |> SparklineSvg.to_svg!()

Reference lines

Reference lines are used to show common reference line on the chart. You can add as many reference lines as you want. Reference lines are displayed as horizontal lines that span the entire width of the chart.

There are currently five basic types of supported reference lines: :max, :min, :avg, :median, and percentile. You can implement custom reference lines.

See the documentation of SparklineSvg.ReferenceLine for more information on how to use.

Window

Window option can be used to set the minimum and maximum value of the x axis of the chart. Normally the window is automatically calculated based on the datapoints. You can set the min or the max value of the window or both.

Outside of window datapoints will be discarded before calculation of the reference lines.

This can be useful to have a consistent chart when the data is not consistent or to have multiple charts with the same window.

Customization

SparklineSvg allows you to customize the chart showing or hiding the dots, the line, and the area under the line as well as markers and reference lines.

There are two ways to customize the chart:

• Using the options like :color or :dasharray.
• Using the CSS classes option to give classes to SVG elements and then using CSS to style them.

Options

svg =
  datapoints
  |> SparklineSvg.new(width: 100, height: 40, padding: 0.5, placeholder: "No data")
  |> SparklineSvg.show_dots(radius: 0.1, color: "rgb(255, 255, 255)")
  |> SparklineSvg.show_line(width: 0.5, color: "rgb(166, 218, 149)")
  |> SparklineSvg.show_area(color: "rgba(166, 218, 149, 0.2)")
  |> SparklineSvg.add_marker(1, stroke_color: "red", stroke_width: 0.5)
  |> SparklineSvg.show_ref_line(:max, width: 0.3, color: "red")
  |> SparklineSvg.to_svg!()

CSS classes

svg =
  datapoints
  |> SparklineSvg.new(width: 100, height: 40, padding: 0.5, placeholder: "No data", class: "sparkline")
  |> SparklineSvg.show_dots(class: "sparkline-dots")
  |> SparklineSvg.show_line(class: "sparkline-line")
  |> SparklineSvg.show_area(class: "sparkline-area")
  |> SparklineSvg.add_marker(1, class: "sparkline-marker")
  |> SparklineSvg.show_ref_line(:max, class: "sparkline-max-value")
  |> SparklineSvg.to_svg!()

Tailwind classes

svg =
  datapoints
  |> SparklineSvg.new(width: 100, height: 40, padding: 0.5, placeholder: "No data", class: "bg-transparent")
  |> SparklineSvg.show_dots(class: "fill-green")
  |> SparklineSvg.show_line(class: "stroke-green stroke-[0.5px] fill-transparent")
  |> SparklineSvg.show_area(class: "fill-green/10")
  |> SparklineSvg.add_marker(1, class: "stroke-red stroke-[0.5px] fill-transparent")
  |> SparklineSvg.show_ref_line(:max, class: "stroke-red stroke-[0.3px]")
  |> SparklineSvg.to_svg!()

When using the CSS classes to style the chart, the other options like :color or :dasharray will be ignored. However, some options (:width, :height, :padding, :smoothing, and :placeholder), are used internally to render the chart and are required in any case.

Available options

Use the following options to customize the chart:

• :width - the width of the chart, defaults to 200.

• :height - the height of the chart, defaults to 50.

• :padding - the padding of the chart, defaults to 2. Not targetable with CSS classes. The padding can be one the following:

  • A single positive number() that will be used for all sides.
  • A keyword list where the keys are :top, :right, :bottom, and :left and the values are a positive number() for each side; missing sides will be set to the default value.

  Padding has to be set to a value which left_padding + right_padding < width and top_padding + bottom_padding < height otherwise a :invalid_dimension error will be raised.

• :smoothing - the smoothing of the line (0 = no smoothing, above 0.4 it becomes unreadable), defaults to 0.15. Not targetable with CSS classes.

• :precision - the maximum precision of the values used to render the chart, defaults to 3. Not targetable with CSS classes. The precision can be set between 0 and 15. The greater the precision, the more accurate the chart will be but the heavier the SVG will be.

• :placeholder - a placeholder for an empty chart, defaults to nil. If set to nil, a chart with no datapoints will be an empty SVG document. Alternatively, you can set it to a string to display a message when the chart is empty. Not targetable with CSS classes.

• :class - the value of the HTML class attribute of the chart, defaults to nil.

• :placeholder_class - the value of the HTML class attribute of the placeholder, defaults to nil. It is the only way to style the placeholder.

• :sort - can be one of these atoms: :asc, :desc, or none. Defaults to :asc. If set to :asc or :desc, the datapoints will be sorted by the x axis before rendering the chart. If set to :none, the datapoints will be rendered in the order they are given, potentially resulting in unexpected visual representations.

Dots options

• :radius - the radius of the dots, defaults to 1.
• :color - the color of the dots, defaults to "black".
• :class - the value of the HTML class attribute of the dots, defaults to nil.

Line options

• :width - the width of the line, defaults to 0.25.
• :color - the color of the line, defaults to "black".
• :dasharray - the value of the HTML stroke-dasharray attribute of the line, defaults to "". Valid dasharray values can be found here.
• :class - the value of the HTML class attribute of the line, defaults to nil.

Area options

• :color - the color of the area under the line, defaults to "rgba(0, 0, 0, 0.1)".
• :class - the value of the HTML class attribute of the area, defaults to nil.

Marker options

• :stroke_width - the stroke width of the marker, defaults to 0.25.
• :stroke_color - the stroke color of the marker, defaults to "red".
• :stroke_dasharray - the value of the HTML stroke-dasharray attribute of the marker, defaults to "". Valid dasharray values can be found here.
• :fill_color - the fill color of an area marker, defaults to "rgba(255, 0, 0, 0.1)".
• :class - the value of the HTML class attribute of the marker, defaults to nil.

Reference line options

• :width - the width of the reference line, defaults to 0.25.
• :color - the color of the reference line, defaults to "rgba(0, 0, 0, 0.5)".
• :dasharray - the value of the HTML stroke-dasharray attribute of the reference line, defaults to "". Valid dasharray values can be found here.
• :class - the value of the HTML class attribute of the reference line, defaults to nil.

Window options

• :min - the minimum value of the window, defaults to :auto. The value must be of the same type as the x axis of the chart, or :auto.
• :max - the maximum value of the window, defaults to :auto. The value must be of the same type as the x axis of the chart, or :auto.