Skip to content

Latest commit

 

History

History
220 lines (165 loc) · 5.82 KB

README.md

File metadata and controls

220 lines (165 loc) · 5.82 KB

nuxt-plotly logo


npm version npm download MIT license nuxt-plotly module on nuxt official


Nuxt Plotly Module

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

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
  1. 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 }]],
});
  1. 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>
  1. 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.