Component | PDF

Render a PDF Preview. This component supports annotations, multi-page documents, and advanced sizing and scrolling options.

Node.js

const buffer = fs.readFileSync("path/to/file.pdf");
ui.pdf(buffer, { style: { width: "500px" }})

Python

with open("path/to/file.pdf", "rb") as f:
    bytes = f.read()

ui.pdf(bytes, style={"width": "500px"})

Sizing and scrolling

By default, the PDF component will take up the full width of the page.

The simplest way to size the PDF is to pass the width property within the style parameter (see first example above). The height will be scaled automatically.

Many PDFs are quite large, so you may want to have the PDF scroll within its container. You can do this by also passing a value for the cross-axis (height). In this case, the container will be sized based on the height parameter, while the PDF will still be responsive to the width parameter, and scroll vertically within the container.

Node.js

const buffer = fs.readFileSync("path/to/file.pdf");
ui.pdf(buffer, { style: { width: "500px", height: "300px" }})

Python

with open("path/to/file.pdf", "rb") as f:
    bytes = f.read()

ui.pdf(bytes, style={"width": "500px", "height": "300px"})

You can flip the default scrolling direction by passing scroll="horizontal" to the component. This will size the container based on the width parameter, while the PDF size will be responsive to the height parameter.

Node.js

const buffer = fs.readFileSync("path/to/file.pdf");
ui.pdf(buffer, { 
  style: { width: "200px", height: "500px" }, 
  scroll: "horizontal" 
})

Python

with open("path/to/file.pdf", "rb") as f:
    bytes = f.read()

ui.pdf(
  bytes, 
  style={"width": "200px", "height": "500px"}, 
  scroll="horizontal"
)

Annotations

You can add annotations on top of the PDF by passing an array of annotation objects.

Each annotation object must have an x1, y1, x2, and y2 property. These fields are numbers that represent the coordinates of the annotation on the page. In order to align the coordinates correctly, you should also size the PDF directly.

Node.js

const buffer = fs.readFileSync("path/to/file.pdf");
ui.pdf(buffer, { 
  style: { width: "500px" }, 
  annotations: [
    {
      x1: 50,
      y1: 50,
      x2: 100,
      y2: 100,
      label: "Hello World"
    },
    {
      x1: 220,
      y1: 405,
      x2: 255,
      y2: 455,
      appearance: "box",
      color: "red",
      label: "Red Box"
    }
  ]
})

Python

with open("path/to/file.pdf", "rb") as f:
    bytes = f.read()

ui.pdf(
  bytes, 
  style={"width": "500px"}, 
  annotations=[
    {
      "x1": 50,
      "y1": 50,
      "x2": 100,
      "y2": 100,
      "label": "Hello World"
    },
    {
      "x1": 220,
      "y1": 405,
      "x2": 255,
      "y2": 455,
      "appearance": "box",
      "color": "red",
      "label": "Red Box"
    }
  ]
)

Annotation object properties

Node.js

x1

required number

The x-coordinate of the top-left corner of the annotation.

Python

x1

required int

The x-coordinate of the top-left corner of the annotation.

---

Node.js

y1

required number

The y-coordinate of the top-left corner of the annotation.

Python

y1

required int

The y-coordinate of the top-left corner of the annotation.

---

Node.js

x2

required number

The x-coordinate of the bottom-right corner of the annotation.

Python

x2

required int

The x-coordinate of the bottom-right corner of the annotation.

---

Node.js

y2

required number

The y-coordinate of the bottom-right corner of the annotation.

Python

y2

required int

The y-coordinate of the bottom-right corner of the annotation.

---

Node.js

appearance

optional string literal

Specify a custom appearance for the annotation. Defaults to "highlight".

Options include:

• "highlight": highlight the annotation.
• "box": Draw a box around the annotation.

Python

appearance

optional Literal

Specify a custom appearance for the annotation. Defaults to "highlight".

Options include:

• "highlight": highlight the annotation.
• "box": Draw a box around the annotation.

---

Node.js

color

optional string literal

Specify a color for the annotation. Defaults to "blue".

Options include:

• "blue"
• "yellow"
• "green"
• "red"
• "purple"
• "orange"
• "gray"

Python

color

optional Literal

Specify a color for the annotation. Defaults to "blue".

Options include:

• "blue"
• "yellow"
• "green"
• "red"
• "purple"
• "orange"
• "gray"

---

Node.js

label

optional string

Specify a label to display alongside the annotation.

Python

label

optional str

Specify a label to display alongside the annotation.

---

Node.js

page

optional number

Specify the page number of the annotation. This should be an integer where 1 is the first page. Defaults to 1.

Python

page

optional int

Specify the page number of the annotation. This should be an integer where 1 is the first page. Defaults to 1.

---

Multi-page documents

There's no special syntax for multi-page documents. Compose will automatically detect when a PDF has multiple pages and render a page navigation widget below the PDF preview.

Annotations default to the first page of the PDF. You can control which page an annotation is on by passing a page property to the annotation object, which should be an integer where 1 is the first page.

API reference

Function signature

Node.js

ui.pdf(
    file: Buffer,
    properties?: Partial<{
        label: string,
        description: string,
        annotations: Annotation[],
        scroll: "vertical" | "horizontal",
        style: Style
    }>
)

Python

ui.pdf(
    file: bytes | io.BufferedIOBase,
    *,
    label: str | None = None,
    description: str | None = None,
    annotations: list[Annotation] | None = None,
    scroll: Literal["vertical", "horizontal"] | None = None,
    style: Style | None = None
)

Parameters

Node.js

file

required Buffer

The PDF file to display. This should be a Buffer.

Python

file

required bytes | io.BufferedIOBase

The PDF file to display. This should be bytes or a bytes-like object that supports the read() method (e.g. BytesIO).

---

Node.js

properties.label

optional string

Display a label above the PDF viewer. If not provided, the label will be left blank.

Python

label

optional str

Display a label above the PDF viewer. If not provided, the label will be left blank.

---

Node.js

properties.description

optional string

Display a small description between the label and the PDF viewer. If not provided, the description will be left blank.

Python

description

optional str

Display a small description between the label and the PDF viewer. If not provided, the description will be left blank.

---

Node.js

properties.annotations

optional Annotation[]

An array of annotation objects to display on the PDF. Each annotation object should follow the Annotation type.

Python

annotations

optional list[Annotation]

An array of annotation objects to display on the PDF. Each annotation object should follow the Annotation type.

---

Node.js

properties.scroll

optional string literal

Specifies the scroll direction for the PDF viewer. Defaults to "vertical".

Options:

• "vertical"
• "horizontal"

See the sizing and scrolling section for more details.

Python

scroll

optional Literal

Specifies the scroll direction for the PDF viewer. Defaults to "vertical".

Options:

• "vertical"
• "horizontal"

See the sizing and scrolling section for more details.

---

Node.js

properties.style

optional Style

Directly style the underlying element using CSS. See the styling guide for more details on available style properties.

Python

style

optional Style | None

Directly style the underlying element using CSS. See the styling guide for more details on available style properties.

---