streamlit-pdf-viewer

Streamlit component that allows the visualisation and enrichment of PDF documents. You can see an application in action here.

Features

• Show PDF files in a Streamlit application with a simple command
• Based on the pdf.js library
• Visualize annotations on top of the PDF documents
• Render text on top of the PDF document, allowing copy-paste
• Allow rendering specific pages of the PDF document
• Scroll to a specific page
• Scroll to a specific annotation
• Allow custom callbacks when an annotation is clicked
• Interactive zoom controls with multiple zoom options
• Configurable alignment of the PDF viewer within its container
• Optional horizontal separators between PDF pages
• Version 0.0.x provides an additional "legacy" viewer using the native pdf.js browser's, with limitations including no annotations, no scrolling - this is removed from version 0.1.x.

Limitations

• Tested and developed to support Firefox and Chrome.
• The legacy visualization works only on Firefox and does not support annotations
• This is a side project, so all troubleshooting may take time
• The component is still in development, so expect some bugs and limitations
• The streamlit reload at each action may render slowly for complex PDF documents

Caveats

Here are some caveats to be aware of:

• It is mandatory to specify a width to show PDF document on tabs and expanders, otherwise, the viewer will not be displayed on tabs not immediately visible.
• From version 0.0.16, the behavior for managing width and height has changed:
  • If only the height is specified, the PDF document will be shown in proportion with the with proportional based on the PDF dimensions.
  • The possibility to show a large view of half the PDF is not available anymore (let's face it, it was not very useful).
  • If you need to use all the available space and limit the height, you can encapsulate the pdf_viewer() into a st.component(width:...) setting the width.
• The legacy rendering has been removed from version 0.1.x+

Streamlit compatibility

Streamlit 1.41–1.58 have a regression in custom-component iframe handling that resets the page scroll position after an st.dialog is closed — see issue #107 for details and the bisect data. This was fixed upstream in Streamlit 1.59.0.

Recommended: use Streamlit ≥ 1.59.0 (verified against the full test suite). Streamlit ≤ 1.40.2 also works. Avoid the 1.41–1.58 range; a runtime UserWarning is emitted at import time when an affected version is detected.

Getting started

pip install streamlit-pdf-viewer

In your streamlit application, you can use it as:

import streamlit as st
from streamlit_pdf_viewer import pdf_viewer

pdf_viewer("str, path or bytes")

You can also customize the viewer with additional options:

import streamlit as st
from streamlit_pdf_viewer import pdf_viewer

# Display PDF with custom zoom, alignment, and separators
pdf_viewer(
    "path/to/your/document.pdf",
    width=700,
    height=1000,
    zoom_level=1.2,                    # 120% zoom
    viewer_align="center",             # Center alignment
    show_page_separator=True           # Show separators between pages
)

Params

In the following table the list of parameters that can be provided to the pdf_viewer function:

Annotation format

The annotation format has been derived from the Grobid's coordinate formats, which are described as a list of "bounding boxes". The annotations are expressed as a dictionary of six elements; the page, x and y indicate the top left point. The color can be expressed following the HTML CSS convention. The border style also follow the HTML conventions limited to these values: solid, dashed, dotted, double, groove, ridge, inset, outset. Any other value will result in the default value: solid.

Annotation unique identifiers are expressed by the id field, if id is not specified, an identifier will be generated during rendering. Furthermore, the HTML identifier will be generated as #annotation-{annotation.id}.

Here is an example:

[
  {
    "page": 1,
    "x": 220,
    "y": 155,
    "height": 22,
    "width": 65,
    "color": "red",
    "border": "solid"
  },
[...]

The example shown in our screenshot can be found here.

Custom callback for clicking on annotations

from streamlit_pdf_viewer import pdf_viewer

annotations = [
    {
        "page": 1,
        "x": 220,
        "y": 155,
        "height": 22,
        "width": 65,
        "color": "red"
    },
    {
        "page": 1,
        "x": 220,
        "y": 155,
        "height": 22,
        "width": 65,
        "color": "red",
        "border": "dotted"
    }
]


def my_custom_annotation_handler(annotation):
    print(f"Annotation {annotation} clicked.")


pdf_viewer(
    "path/to/pdf",
    on_annotation_click=my_custom_annotation_handler,
    annotations=annotations
)

Developers notes

Environment

• Python >= 3.8
• Node.js >= 16
• Streamlit >= 1.28.2

Configure environment for development

First, make sure that _RELEASE = False in streamlit_pdf_viewer/__init__.py. To run the component in development mode, use the following commands:

streamlit run streamlit_pdf_viewer/__init__.py

cd frontend
npm run serve

These commands will start the Streamlit application and serve the Node.js component. Please make sure you're in the correct directory before running these commands.

Integrate into a streamlit application

1. Build the frontend part:

   cd frontend
   export NODE_OPTIONS=--openssl-legacy-provider
   npm run build 
   

2. Make sure that _RELEASE = True in streamlit_pdf_viewer/__init__.py.

3. move to the streamlit_application and run

   pip install -e {path of component}
   

Release

bump-my-version bump patch | minor | major

git push
git push --tags 

Acknowledgement

The project was initiated by Luca Foppiano at the National Institute for Materials Science (NIMS) in Japan. Currently, the development is possible thanks to ScienciLAB.

Main contacts: Luca Foppiano and Tomoya Mato.