“HTML documents are nothing new. They are what powers the internet and all the websites that we visit. Therefore, you will come across instances where you need to export a Plotly figure into an HTML document. You can then share that document or upload it to a web server as a static page.”

In this article, we will explore how we can use the to_html function from the Plotly io module to export a figure into an HTML string.

Function Syntax and Parameter List

The function has a relatively simple syntax, as shown below:, config=None, auto_play=True, include_plotlyjs=True, include_mathjax=False, post_script=None, full_html=True, animation_opts=None, default_width='100%', default_height='100%', validate=True, div_id=None)


  1. fig – specifies the figure to convert into an HTML string.
  2. config – defines the plotly.js configuration options.
  3. auto_play – specifies whether the figure animation, if any, should automatically start after page load.
  4. include_plotlyjs – defines the method in which the Plotly.js library is included in the HTML file. Accepted options include:
    1. True – Plotly.js is included as a script tag containing the source code for the Plotly.js library. This can lead to the offline use of the files but leads to a large file size.
    2. ‘cdn’ – this option includes the Plotly.js library as a script tag that references a CDN link.
    3. ‘directory’ – if set to a directory, the function will include the Plotly.js library as an external plotly.min.js bundle stored in the same directory as the HTML file.
    4. ‘require’ – If set to require, Plotly.js is loaded using require.js.
    5. False – Plotly.js is not included in the HTML file.
  5. include_mathjax – specifies how the mathjax.js library is included. Accepted options are similar to the plotly.js library.
  6. post_script – Specifies the JavaScript snippets included in the div after plot creation.
  7. Full_html – sets if the function should convert the figure into an entire HTML document starting with <html> tags or a partial HTML string starting with the <div> element.
  8. validate – specifies if the figure should be validated before converting to HTML.

The function will then return an HTML string representing the specified figure.

Create Sample Figure

Before we learn how to convert a figure into an HTML string, let us have sample data we can use.

For this tutorial, we will use a simple Sunburst figure as shown in the code below:

import as px
data = dict(
    distros=['Debian', 'CentOS', 'Fedora', 'Red Hat Linux', 'OpenSUSE', 'Qubes', 'SUSE Studio', 'Ubuntu', 'Kubuntu', 'Xubuntu'],
    parents=['', 'Red Hat Linux', 'Red Hat Linux', '', 'Red Hat Linux', 'Fedora', 'OpenSUSE', 'Debian', 'Ubuntu', 'Ubuntu']
fig = px.sunburst(data, names='distros', parents='parents', color='distros')

The code above should return a figure as shown:

Export Figure as HTML String

To export the figure above as a static HTML string, we can run the code as shown:

import as io
io.to_html(fig, include_plotlyjs='cdn')

The code above will return an HTML string representing the above sunburst plot. Keep in mind that the html string will include the plotly.js library as CDN as specified above.

From the output above, we can see that the HTML document starts at the <div> element.

To generate a full HTML document, we can set the full_html parameter to true as shown:

import as io
io.to_html(fig, include_plotlyjs='cdn', full_html=True)

Save HTML String to File

One useful feature of the to_html function is writing the resulting HTML string to an HTML file.

An example is as shown:

import as io
with open('sunburst.html', 'w') as f:
    f.write(io.to_html(fig, include_plotlyjs='cdn', full_html=True))

The code above should write the HTML string from the to_html function into the sunburst.html file.

You can then view this file by opening it in your browser.

Since we include the plotly.js library as a CDN, you will require a network connection for the library to download and get the full interactivity of the figure.


In this article, we learned how we could convert a Plotly figure into an HTML string using the io.to_html() function.

Thanks for reading &Happy coding!!

About the author

John Otieno

My name is John and am a fellow geek like you. I am passionate about all things computers from Hardware, Operating systems to Programming. My dream is to share my knowledge with the world and help out fellow geeks. Follow my content by subscribing to LinuxHint mailing list