Skip to content
React PDF Kit logo - WHITE React PDF Kit Logo
useElementThumbnailContext Organization

The useElementThumbnailContext hook in React PDF Kit provides functions to add custom elements onto a PDF thumbnail and to scroll the thumbnail panel to a specific element.

It enables you to overlay a checkbox, badge, marker or any custom UI on top of a thumbnail for a specified page.

This is useful for building thumbnail-based interactions such as page selection, page deletion or annotation indicators.

Return Type

Section titled “Return Type”
NameTypeDescriptionversion
clearElements(pageNumber: number) => voidRemove all custom elements from the specific thumbnail page2.5.0
elementListRecord<number, Array<HTMLElement | JSX.Element>>The current map of custom elements per thumbnail page2.5.0
removeElement(pageNumber: number, index: number) => voidRemove a custom element from the specific thumbnail page by its index2.5.0
scrollToElement(page: number, index: number, config?: { behavior: ‘smooth’ | ‘auto’ | ‘instant’ }) => voidScroll the thumbnail panel so that a specific element on the given thumbnail page is visible. The default scroll behavior follows the scrollBehavior prop of RPController and falls back to smooth2.5.0
updateElement(pageNumber: number, element: (prevElements, dimension: {width: number, height: number}, rotate: number) => Array<HTMLElement | JSX.Element>) => voidAdd or update custom elements on the specific thumbnail page2.5.0

The thumbnail panel must be visible (i.e. the thumbnail sidebar is open) for scrollToElement to take effect.

Usage

Section titled “Usage”

To ensure the element thumbnail context can be accessed, you will need to use useElementThumbnailContext inside a component which is a child of RPProvider.

This example shows how to create a CustomThumbnailSelector component which uses useElementThumbnailContext to render a per-thumbnail selection checkbox and to scroll the thumbnail panel to a chosen page’s checkbox.

    import { useCallback, useEffect, useState } from 'react'
    import {
      RPConfig,
      RPProvider,
      RPLayout,
      RPPages,
      useElementThumbnailContext,
      usePaginationContext
    } from '@react-pdf-kit/viewer'


    const CustomThumbnailSelector = () => {
      const { updateElement, clearElements, scrollToElement } = useElementThumbnailContext()
      const { totalPages } = usePaginationContext()
      const [selectedPages, setSelectedPages] = useState([])
      const [scrollPage, setScrollPage] = useState(1)


      const togglePage = useCallback((page) => {
        setSelectedPages((prev) =>
          prev.includes(page) ? prev.filter((p) => p !== page) : [...prev, page]
        )
      }, [])


      // render a checkbox in the top-right corner of every thumbnail
      useEffect(() => {
        if (!totalPages) return
        for (let page = 1; page <= totalPages; page++) {
          const isSelected = selectedPages.includes(page)
          updateElement(page, () => [
            <div
              key={`thumb-checkbox-${page}`}
              onClick={(e) => {
                e.stopPropagation()
                togglePage(page)
              }}
              style={{
                position: 'absolute',
                top: 4,
                right: 4,
                width: 18,
                height: 18,
                borderRadius: 4,
                backgroundColor: isSelected ? '#2563eb' : '#ffffff',
                border: '2px solid #2563eb',
                cursor: 'pointer',
                zIndex: 2
              }}
            />
          ])
        }
        return () => {
          for (let page = 1; page <= totalPages; page++) {
            clearElements(page)
          }
        }
      }, [totalPages, selectedPages, togglePage, updateElement, clearElements])


      const handleScrollToCheckbox = useCallback(() => {
        // scroll to the first (index 0) custom element on the chosen thumbnail page
        scrollToElement(scrollPage, 0, { behavior: 'smooth' })
      }, [scrollPage, scrollToElement])


      return (
        <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
          <span>Selected: {selectedPages.sort((a, b) => a - b).join(', ') || '(none)'}</span>
          <input
            type="number"
            min={1}
            max={totalPages || 1}
            value={scrollPage}
            onChange={(e) => setScrollPage(Number(e.target.value))}
            style={{ width: 64 }}
          />
          <button onClick={handleScrollToCheckbox}>scroll thumbnail to page</button>
        </div>
      )
    }


    export const AppPdfViewer = () => {
      return (
        <RPConfig licenseKey="YOUR_DOMAIN_TOKEN">
          <RPProvider src="https://cdn.codewithmosh.com/image/upload/v1721763853/guides/web-roadmap.pdf">
            <CustomThumbnailSelector />
            <RPLayout toolbar>
              <RPPages />
            </RPLayout>
          </RPProvider>
        </RPConfig>
      )
    }

Notes on scrollToElement

Section titled “Notes on scrollToElement”
  • page is the 1-based PDF page number whose thumbnail should be scrolled into view.
  • index is the position of the element within elementList[page] (the same order they were appended via updateElement).
  • config.behavior accepts 'smooth', 'auto' or 'instant'. When omitted, the value of the scrollBehavior prop of the RPController component is used and falls back to 'smooth'.
  • The thumbnail sidebar must be visible. If the sidebar is collapsed when this is called, no scroll occurs.