README.md

Nuxt Plotly Module

📊 nuxt-plotly module is thin Nuxt3 wrapper for plotly.js

• 🏀 Online playground
• 📖  Plotly Documentation

Features

• 🎇   All plotly.js methods and events
• 🗾   Auto redraw on screensize changes and props update
• 🚀   Data reactivity
• 🏝️   TypeScript support

Quick Setup

1. Add nuxt-plotly dependency to your project

npx nuxi@latest module add nuxt-plotly

2. Add nuxt-plotly to the modules section of nuxt.config.ts

// nuxt.config.js
export default defineNuxtConfig({
  /**
   * Add nuxt-plotly module
   */
  modules: ["nuxt-plotly"],

  /**
   * Add nuxt-plotly module with options
   * Set the inject option to true to use plotly function via $plotly
   */
  // modules: [["nuxt-plotly", { inject: true }]],
});

3. Add plotly.js-dist-min to the vite.optimizeDeps.include section of nuxt.config.ts

// nuxt.config.js
export default defineNuxtConfig({
  vite: {
    optimizeDeps: {
      include: ["plotly.js-dist-min"],
    },
  },
});

That's it! You can now use Nuxt Plotly Module in your Nuxt app ✨

Require client-side

There are two ways to use the nuxt-plotly module on the client-side in Nuxt3:

1. Wrap the component with the <client-only> tag.

<client-only>
  <nuxt-plotly
    :data="pieChart.data"
    :layout="pieChart.layout"
    :config="pieChart.config"
    style="width: 100%"
  ></nuxt-plotly>
</client-only>

2. Create a file with the .client.vue extension, for example, PieChart.client.vue and then you can use the component without the <client-only> tag.

Plotly Event listeners

You can access Plotly events using the @on-ready directive to receive the PlotlyHTMLElement object from the <nuxt-plotly> component.

• HTML template example

<template>
  <client-only>
    <nuxt-plotly
      :data="data"
      :layout="layout"
      :config="config"
      @on-ready="myChartOnReady"
    ></nuxt-plotly>
  </client-only>
</template>

• After receiving the PlotlyHTMLElement, you can access Plotly events

function myChartOnReady(plotlyHTMLElement: NuxtPlotlyHTMLElement) {
  console.log({ plotlyHTMLElement });

  plotlyHTMLElement.on?.("plotly_afterplot", function () {
    console.log("done plotting");
  });

  plotlyHTMLElement.on?.("plotly_click", function () {
    alert("You clicked this Plotly chart!");
  });
}

Plotly Functions

To use the Plotly Function in your nuxt project, follow these steps:

• Step 1: Set the inject option to true in the nuxt-plotly module configuration of your nuxt.config.ts file.

// nuxt.config.js
export default defineNuxtConfig({
  modules: [["nuxt-plotly", { inject: true }]],
});

• Step 2: After setting the inject option to true, you can now access the plotly function via $plotly in your nuxt project.

// app.vue

const { $plotly } = useNuxtApp();

/**
 * Show all plotly functions
 */
console.log($plotly);

/**
 * Use downloadImage function
 */
$plotly.downloadImage(plotlyHTMLElement as HTMLElement, {
  format: "png",
  width: 800,
  height: 600,
  filename: "newplot",
});

Type Aliases

These type aliases simplify the usage of Plotly types in your Nuxt project:

/**
 * Represents an array of Plotly data objects.
 */
export type NuxtPlotlyData = Array<Plotly.Data>;

/**
 * Represents a partial configuration object for Plotly charts.
 */
export type NuxtPlotlyConfig = Partial<Plotly.Config>;

/**
 * Represents a partial layout object for Plotly charts.
 */
export type NuxtPlotlyLayout = Partial<Plotly.Layout>;

/**
 * Represents a partial HTML element that holds a rendered Plotly chart.
 */
export type NuxtPlotlyHTMLElement = Partial<Plotly.PlotlyHTMLElement>;

With these type aliases, you can easily work with Plotly data, configurations, layouts, and HTML elements in your Nuxt application, enhancing your experience when creating interactive charts and visualizations.

Development: If you want to contribute

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch

# Release new version
npm run release

License

Copyright © 2023 Supanut Dokmaithong.

This project is MIT licensed.