Rasterex APINPM Package/docs/components/files/page-selection

Page Selection

Navigate to a page from the host UI using page indexes or page numbers programmatically.

Overview

When a user interacts with a page sidebar, select tabs, or click index links in your parent UI, command the Canvas to navigate viewport focuses using the documents API.

The SDK exposes selectPage to scroll directly to targeted locations, resolving immediately and broadcasting the final active state through the pageList and pageChanged streams.

Flexible Referencing: Select target pages using either 0-based page indices or 1-based human-facing page numbers.
Promise-Driven Resolution: Await execution directly at call sites to confirm successful brokerage.
State Synchronization: Treat subsequent active indicators inside the pageList event payload as the final state confirmation.

Quick Start

Command viewport page selection programmatically using these SDK options:

Select by page index

// Scrolls to the 3rd page (0-based index)
await viewer.documents.selectPage({ pageIndex: 2 });

Select by page number

// Scrolls to the 3rd page (1-based page number)
await viewer.documents.selectPage({ pageNumber: 3 });

Vanilla Integration

Copy these project setup files to configure mounting, file load, and direct page selection bindings:

import { createViewer } from "@rasterex/viewer";
import "./style.css";

const viewer = createViewer({
  container: "#viewer"
});

async function startViewer() {
  await viewer.mount();
  await viewer.ready();

  await viewer.documents.open({
    url: "https://pdfobject.com/pdf/sample.pdf",
    displayName: "sample.pdf"
  });
}

async function handlePageSelect(pageIndex) {
  try {
    await viewer.documents.selectPage({ pageIndex });
  } catch (error) {
    console.error("Could not navigate:", error);
  }
}

document.querySelector("#prev-page")?.addEventListener("click", () => {
  const current = viewer.getInfo().currentPage || 0;
  if (current > 0) {
    handlePageSelect(current - 1).catch(console.error);
  }
});

document.querySelector("#next-page")?.addEventListener("click", () => {
  const current = viewer.getInfo().currentPage || 0;
  handlePageSelect(current + 1).catch(console.error);
});

startViewer().catch(console.error);

Vanilla Integration

React Integration

Control viewport page navigation inside a React custom pager bar:

import { useEffect, useRef, useState } from "react";
import { createViewer, type RasterexViewer } from "@rasterex/viewer";
import "./style.css";

export function PageSelectionExample() {
  const containerRef = useRef<HTMLDivElement | null>(null);
  const viewerRef = useRef<RasterexViewer | null>(null);
  const [currentPage, setCurrentPage] = useState(0);

  useEffect(() => {
    if (!containerRef.current) return undefined;

    const viewer = createViewer({ container: containerRef.current });
    viewerRef.current = viewer;

    const unsubscribe = viewer.documents.on("pageList", (event) => {
      setCurrentPage(event.currentPage);
    });

    async function start(): Promise<void> {
      await viewer.mount();
      await viewer.ready();
      await viewer.documents.open({
        url: "https://pdfobject.com/pdf/sample.pdf",
        displayName: "sample.pdf"
      });
    }

    void start().catch(console.error);

    return () => {
      unsubscribe();
      viewer.destroy();
      viewerRef.current = null;
    };
  }, []);

  async function goToPage(pageIndex: number): Promise<void> {
    if (pageIndex < 0) return;
    await viewerRef.current?.documents.selectPage({ pageIndex });
  }

  return (
    <div>
      <div className="toolbar">
        <button type="button" onClick={() => void goToPage(currentPage - 1)}>
          Previous
        </button>
        <span>Page Index: {currentPage}</span>
        <button type="button" onClick={() => void goToPage(currentPage + 1)}>
          Next
        </button>
      </div>
      <div ref={containerRef} style={{ height: 600 }} />
    </div>
  );
}

React Integration

Vue Integration

Control viewport page navigation inside a Vue composition component:

<script setup lang="ts">
import { onBeforeUnmount, onMounted, ref, shallowRef } from "vue";
import { createViewer, type RasterexViewer } from "@rasterex/viewer";
import "./style.css";

const containerRef = ref<HTMLElement | null>(null);
const viewerRef = shallowRef<RasterexViewer | null>(null);
const currentPage = ref(0);

let unsubscribe: (() => void) | undefined;

onMounted(async () => {
  if (!containerRef.value) return;

  const viewer = createViewer({ container: containerRef.value });
  viewerRef.value = viewer;

  unsubscribe = viewer.documents.on("pageList", (event) => {
    currentPage.value = event.currentPage;
  });

  try {
    await viewer.mount();
    await viewer.ready();

    await viewer.documents.open({
      url: "https://pdfobject.com/pdf/sample.pdf",
      displayName: "sample.pdf"
    });
  } catch (error) {
    console.error(error);
  }
});

onBeforeUnmount(() => {
  unsubscribe?.();
  viewerRef.value?.destroy();
  viewerRef.value = null;
});

async function goToPage(pageIndex: number) {
  if (pageIndex < 0) return;
  await viewerRef.value?.documents.selectPage({ pageIndex });
}
</script>

<template>
  <div>
    <div class="toolbar">
      <button type="button" @click="goToPage(currentPage - 1)">Previous</button>
      <span>Page Index: {{ currentPage }}</span>
      <button type="button" @click="goToPage(currentPage + 1)">Next</button>
    </div>
    <div ref={containerRef} style="height: 600px" />
  </div>
</template>

Vue Integration

Angular Integration

Control viewport page navigation inside standalone Angular template bindings:

import {
  AfterViewInit,
  Component,
  ElementRef,
  OnDestroy,
  ViewChild
} from "@angular/core";
import { createViewer, type RasterexViewer } from "@rasterex/viewer";

@Component({
  selector: "app-page-selection",
  templateUrl: "./page-selection.component.html"
})
export class PageSelectionComponent implements AfterViewInit, OnDestroy {
  @ViewChild("viewerContainer", { static: true })
  viewerContainer!: ElementRef<HTMLElement>;

  currentPage = 0;
  private viewer: RasterexViewer | null = null;
  private unsubscribe?: () => void;

  async ngAfterViewInit(): Promise<void> {
    const viewer = createViewer({
      container: this.viewerContainer.nativeElement
    });

    this.viewer = viewer;

    this.unsubscribe = viewer.documents.on("pageList", (event) => {
      this.currentPage = event.currentPage;
    });

    try {
      await viewer.mount();
      await viewer.ready();

      await viewer.documents.open({
        url: "https://pdfobject.com/pdf/sample.pdf",
        displayName: "sample.pdf"
      });
    } catch (error) {
      console.error(error);
    }
  }

  async goToPage(pageIndex: number): Promise<void> {
    if (pageIndex < 0) return;
    await this.viewer?.documents.selectPage({ pageIndex });
  }

  ngOnDestroy(): void {
    this.unsubscribe?.();
    this.viewer?.destroy();
  }
}

Angular Integration

Live Preview

Open the focused demo to click page cards and watch selectPage commands and pageChanged events live.

File Page Selection Demo

Focused live demo for page selection.

Preview opens in a large modal for zoom-friendly review.