API Reference

---

Methods

makeStory()

Creates a

Story

instance.

const makeStory = (div: HTMLDivElement, steps: InputStep[], options?: StoryOptions): Story

Arguments

The first argument is a

div

element that will be used as a container for the story (an

svg

element will be appended to it). As Plotteus is responsive by design, chart will simply take the full size of the container.

The second argument is an array of

InputStep

objects that contain definitions of steps that together form a story.

The third argument is an optional object that contains options for the story.

Returns

A

Story

object that contains a

render

method.

Story.render = (
  stepKey: string, // key of the step to render
  progress: number, // progress of the step to render (0-1)
  indicateProgress?: boolean // whether to indicate progress (left border)
): void

---

Types

InputStep

Arguably, the most important piece of the API. It defines a step of the story.

type InputStep = {
  // Unique identifier of a step.
  // Passed as a first argument to the render method.
  key: string;
  title?: string;
  titleAnchor?: "start" | "middle" | "end";
  subtitle?: string;
  subtitleAnchor?: "start" | "middle" | "end";
  // If true, shares the color domain between groups.
  shareDomain?: boolean;
  showLegend?: boolean;
  legendTitle?: string;
  legendAnchor?: "start" | "middle" | "end";
  showValues?: boolean;
  showDatumLabels?: boolean;
  palette?: "default" | "pastel" | "vivid" | "oranges" | "tableau";
  // If true, enables hand-drawn look.
  cartoonize?: boolean;
} & (
  | ({
      chartType: "bar";
      chartSubtype?: "grouped" | "stacked";
      valueScale?: {
        // Compares the maximum value set by the user with the maximum value
        // found within the group.
        maxValue?: number;
      };
      groups: Array<{
        // Unique identifier of a group.
        // Used to match and animate the groups between consecutive steps.
        key: string;
        opacity?: number;
        data: Array<{
          // Unique identifier of a datum.
          // Used to match and animate the data inside a given group between
          // consecutive steps.
          key: string;
          value: number;
          // Used to teleport datum between groups. Formatted as "groupKey:datumKey".
          teleportFrom?: string;
          // HEX, e.g. "#CCCCCC"
          fill?: string;
          opacity?: number;
        }>;
      }>;
    } & (
      | {
          layout?: "vertical";
          verticalAxis?: {
            show?: boolean;
            title?: string;
            tickFormat?: (d: number) => string;
          };
        }
      | {
          layout?: "horizontal";
          horizontalAxis?: {
            show?: boolean;
            title?: string;
            tickFormat?: (d: number) => string;
          };
        }
    ))
  | ({
      chartType: "beeswarm";
      positionScale?: {
        minValue?: number;
        maxValue?: number;
      };
      groups: Array<{
        // Unique identifier of a group.
        // Used to match and animate the groups between consecutive steps.
        key: string;
        opacity?: number;
        data: Array<{
          // Unique identifier of a datum.
          // Used to match and animate the data inside a given group between
          // consecutive steps.
          key: string;
          position: number;
          // Used to teleport datum between groups. Formatted as "groupKey:datumKey".
          teleportFrom?: string;
          // HEX, e.g. "#CCCCCC"
          fill?: string;
          opacity?: number;
        }>;
      }>;
    } & (
      | {
          layout?: "vertical";
          verticalAxis?: {
            show?: boolean;
            title?: string;
            tickFormat?: (d: number) => string;
          };
        }
      | {
          layout?: "horizontal";
          horizontalAxis?: {
            show?: boolean;
            title?: string;
            tickFormat?: (d: number) => string;
          };
        }
    ))
  | {
      chartType: "bubble" | "pie" | "treemap";
      valueScale?: {
        // Useful for fixing the value scale domain to show evolution of values.
        maxValue?: number;
      };
      groups: Array<{
        // Unique identifier of a group.
        // Used to match and animate the groups between consecutive steps.
        key: string;
        opacity?: number;
        data: Array<{
          // Unique identifier of a datum.
          // Used to match and animate the data inside a given group between
          // consecutive steps.
          key: string;
          value: number;
          // Used to teleport datum between groups. Formatted as "groupKey:datumKey".
          teleportFrom?: string;
          // HEX, e.g. "#CCCCCC"
          fill?: string;
          opacity?: number;
        }>;
      }>;
    }
  | {
      chartType: "scatter";
      xScale?: {
        // Useful for fixing the x scale domain to show evolution of values.
        minValue?: number;
        maxValue?: number;
      };
      yScale?: {
        // Useful for fixing the y scale domain to show evolution of values.
        minValue?: number;
        maxValue?: number;
      };
      horizontalAxis?: {
        show?: boolean;
        title?: string;
        tickFormat?: (d: number) => string;
      };
      verticalAxis?: {
        show?: boolean;
        title?: string;
        tickFormat?: (d: number) => string;
      };
      groups: Array<{
        // Unique identifier of a group.
        // Used to match and animate the groups between consecutive steps.
        key: string;
        opacity?: number;
        data: Array<{
          // Unique identifier of a datum.
          // Used to match and animate the data inside a given group between
          // consecutive steps.
          key: string;
          x: number;
          y: number;
          // Used to teleport datum between groups. Formatted as "groupKey:datumKey".
          teleportFrom?: string;
          // HEX, e.g. "#CCCCCC"
          fill?: string;
          opacity?: number;
        }>;
      }>;
    }
);

StoryOptions

Optional object that contains options for the story.

type InputStoryOptions = {
  // HEX color of the background of the SVG.
  svgBackgroundColor?: string;
};