Plotly.NET Documentation

Plotly.NET generates JSON that is consumed by plotly.js. Therefore, to render charts in a UI library, the environment must be able to execute JavaScript and display HTML.

• Web-based UI (e.g., Blazor): Requires a way to display HTML/JS.
• Desktop (Windows Forms / WPF): Can use a WebView control to display the interactive charts.
• Static Rendering: If your UI cannot run JavaScript, use Plotly.NET.ImageExport on the backend to generate static images of the charts to be served to the UI.

Plotly.NET is composed of several layers to support different workflows:

• Plotly.NET (Core): The foundation, written in F#. It provides high-level type-safe APIs (like Chart) and low-level chart object manipulation. It is interoperable with C#.
• Plotly.NET.CSharp: A thin wrapper around the core API written in C#. It is designed to make the library more idiomatic and ergonomic for C# developers.
• Plotly.NET.Interactive: Specialized for notebook environments to enable interactive rendering.
• Plotly.NET.ImageExport: Used for programmatic conversion of charts into static images.

Plotly.NET supports the plotly.js >= 2.28.0 encoded data_array format. This format allows for faster transport of large trace data fields (like x, y, z, and error arrays) by using a base64 encoded payload instead of plain sequences.

To use this feature, you can provide values via parallel ...Encoded optional parameters using the EncodedTypedArray type. If both a plain sequence (e.g., x) and an encoded version (e.g., XEncoded) are provided, the encoded version takes precedence during serialization.

// Conceptual usage of encoded parameters
// Note: Exact API syntax depends on the specific trace implementation
Chart.Scatter
    |> Scatter.setXEncoded (EncodedTypedArray.ofFloat64Array(flatArray, shape = [| rows; cols |]))
    |> Chart.show

Plotly.NET uses a specific F# pattern to provide a unified Chart API across multiple files without requiring the user to change how they call methods.

Each chart family (e.g., 2D, 3D, Map) is defined in its own module using the [<AutoOpen>] attribute and an [<Extension>] type named Chart. When these modules are opened, the compiler resolves the static members as extension methods on the base Plotly.NET.Chart type.

This allows a developer to call Chart.Scatter(...) or Chart.Surface(...) uniformly, even though the underlying implementation resides in different physical files (like Chart2D.fs or Chart3D.fs).

[<AutoOpen>]
module Chart2D =
    [<Extension>]
    type Chart =
        [<Extension>]
        static member Scatter(...) = ...

To use Plotly.NET in C# projects, add the Plotly.NET.CSharp package.

In Polyglot Notebooks

Reference both Plotly.NET.Interactive and Plotly.NET.CSharp using the #r "nuget: ..." syntax. Use the Plotly.NET.CSharp namespace to access the idiomatic API.

#r "nuget: Plotly.NET.Interactive"
#r "nuget: Plotly.NET.CSharp"

using Plotly.NET.CSharp;

Chart.Point<int, int, string>(
    x: Enumerable.Range(0,11),
    y: Enumerable.Range(0,11)
)

To use Plotly.NET in F# projects, add the Plotly.NET package.

In Polyglot Notebooks

Reference the Plotly.NET.Interactive package using the #r "nuget: ..." syntax. To display a chart, ensure the cell ends with the chart object.

In .fsx Scripts

Reference the Plotly.NET package. To display a chart in your browser, pipe the chart object to Chart.show.

// Polyglot Notebook
#r "nuget: Plotly.NET.Interactive"

open Plotly.NET

Chart.Point(
    x = [0 .. 10],
    y = [0 .. 10]
)
|> Chart.withTitle "Hello World!"

// .fsx Script
#r "nuget: Plotly.NET"

open Plotly.NET

Chart.Point(
    x = [0 .. 10],
    y = [0 .. 10]
)
|> Chart.withTitle "Hello World!"
|> Chart.show

To reproduce the package for local testing or development, run the ./Repack.ps1 script in PowerShell. This script performs the following actions:

1. Cleans your local NuGet cache in ~/.nuget/packages.
2. Packs the library into the Plotly.NET/pkg folder.

Note: The version of the reproduced package is always 0.0.0-dev.

When working with locally reproduced packages in an interactive notebook (like Polyglot Notebooks), you must use absolute paths in the #i directive to point to the directory containing your local NuGet packages. Use the #r directive to reference specific packages and versions.

Example configuration:

• Use #i "nuget: <ABSOLUTE_PATH_TO_PKG_FOLDER>" to initialize the local package source.
• Use #r "nuget: <PackageName>, <Version>" to load the specific libraries.

// Use absolute paths for local nuget packages
#i "nuget: C:/Users/schne/source/repos/plotly/Plotly.NET/pkg"
#r "nuget: Plotly.NET, 0.0.1-dev"
#r "nuget: Plotly.NET.Interactive, 0.0.1-dev"

After creating a chart, you can use the following methods to refine its properties:

• Chart.withZAxisStyle(name, MinMax): Sets the name of the Z-axis and defines its minimum and maximum range.
• Chart.withConfig(config): Updates the chart's configuration. For example, you can change the default export format of the 'Download plot' button using ConfigObjects.ToImageButtonOptions.init(Format=...).