leptos_pdf/lib.rs
1//! # [`leptos-pdf`](crate)
2//!
3//! [`leptos-pdf`](crate) is a lightweight Leptos component library for rendering and viewing PDF files
4//! in a Leptos app using [PDFium](https://pdfium.googlesource.com/pdfium/) via the
5//! [`pdfium-render`](https://crates.io/crates/pdfium-render) crate.
6//!
7//! It provides an idiomatic Leptos interface for embedding PDFs in Rust + WebAssembly apps, with
8//! canvas-based rendering.
9//!
10//! ## Installation and Supported Leptos Versions
11//!
12//! Add [`leptos-pdf`](crate) to your project using the version that matches your Leptos version:
13//!
14//! | **Leptos Version** | **Command** |
15//! |:------------------:|:--------------------------:|
16//! | 0.8 | `cargo add leptos-pdf@0.8` |
17//! | 0.7 | `cargo add leptos-pdf@0.7` |
18//!
19//! Each [`leptos-pdf`](crate) release tracks the same minor version of Leptos (e.g. [`leptos-pdf`](crate) 0.8.x works with [`leptos`] 0.8.x).
20//!
21//! ## Example
22//!
23//! ```rust
24//! use leptos::prelude::*;
25//! use leptos_pdf::prelude::*;
26//!
27//! #[component]
28//! fn App() -> impl IntoView {
29//! view! {
30//! <main>
31//! <div style:width="100vw" style:height="100vh">
32//! <PdfiumProvider>
33//! // If the pdfium-bundled feature is not enabled, you must provide your own URL:
34//! //
35//! // <PdfiumProvider src="/public/pdfium/pdfium.js">
36//! //
37//! // With this setup, make sure that /public/pdfium/pdfium.wasm also exists, and
38//! // you modify your index.html to include these files
39//! <PdfViewer
40//! url="/public/sample.pdf"
41//! loading_fallback=move || view! { <p>"Loading..."</p> }
42//! error_fallback=move |e| {
43//! view! { <p>"An error occurred..."</p> }
44//! }
45//! />
46//! </PdfiumProvider>
47//! </div>
48//! </main>
49//! }
50//! }
51//!
52//! fn main() {
53//! mount_to_body(App)
54//! }
55//!
56//! ```
57//!
58//! See the [`components`] module for more information on PDF rendering.
59//!
60//! ## Getting Started
61//!
62//! PDFium is a vendor dependency (JavaScript + WASM). You can provide it in one of two ways:
63//!
64//! 1. **Manual assets (recommended if you want full control).**
65//!
66//! Download the PDFium WASM distribution from the
67//! [pdfium-binaries repository](https://github.com/bblanchon/pdfium-binaries) (grab the latest
68//! WASM release), and place the files in your app's assets directory (for example, `public/`).
69//!
70//! If you use Trunk, ensure the directory is copied into the build output:
71//!
72//! ```html
73//! <link data-trunk rel="copy-dir" href="public/" />
74//! ```
75//!
76//! Then initialize PDFium with [`PdfiumProvider`](crate::components::PdfiumProvider) and point it
77//! at your `pdfium.js`:
78//!
79//! ```rust
80//! use leptos::prelude::*;
81//! use leptos_pdf::prelude::*;
82//!
83//! #[component]
84//! fn Demo() -> impl IntoView {
85//! view! {
86//! <PdfiumProvider src="/public/pdfium/pdfium.js">
87//! // ...
88//! </PdfiumProvider>
89//! }
90//! }
91//! ```
92//!
93//! Make sure the referenced `pdfium.js` can locate its accompanying `pdfium.wasm` (typically by
94//! keeping them in the same directory).
95//!
96//! For more information on how to bundle PDFium, see
97//! [`pdfium-render`'s guide on compiling to WASM](https://github.com/ajrcarey/pdfium-render/tree/master?tab=readme-ov-file#compiling-to-wasm).
98//!
99//! 2. **Bundled assets (zero setup).**
100//!
101//! Enable the `pdfium-bundled` feature when adding [`leptos-pdf`](crate). This embeds PDFium's
102//! JavaScript and WASM bytes into your binary and serves them via `blob:` URLs at runtime.
103//! This is the easiest option, but the embedded PDFium version are not updated on a fixed schedule.
104//!
105//! ## Features
106//!
107//! - `pdfium-bundled`: Embed PDFium's JavaScript and WASM and serve them via `blob:` URLs at runtime.
108
109pub mod components;
110pub mod errors;
111pub mod prelude;