feat: add allow_clickable_annotations_with_text_rendering option

[anatolec]

Summary

This PR adds a new parameter allow_clickable_annotations_with_text_rendering that allows annotations to remain clickable even when render_text=True.

Currently, when render_text=True, annotations become non-interactive (pointer-events: none). This makes it impossible to have both text selection and clickable annotations in the same viewer.

Changes

• Added allow_clickable_annotations_with_text_rendering parameter (defaults to False)
• When enabled, annotations use pointer-events: auto and z-index: 12 (above text layer)
• Click handlers are always attached when annotations are clickable

Usage

pdf_viewer(
    pdf_bytes,
    render_text=True,
    annotations=my_annotations,
    allow_clickable_annotations_with_text_rendering=True,
    on_annotation_click=handle_click,
)

Trade-off

Text selection will not work through annotation areas when this option is enabled.

Defaults to False to maintain backward compatibility.

Summary by CodeRabbit

• New Features
  • Added a new configuration option to enable clickable annotations when text rendering is active in PDF documents.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

A new optional parameter allow_clickable_annotations_with_text_rendering is added to the pdf_viewer function, enabling annotations to remain clickable when text rendering is enabled. The parameter is propagated from the Python backend to the Vue frontend component, which conditionally adjusts annotation interactivity, cursor style, and z-index layering.

Changes

Cohort / File(s)	Summary
Backend Parameter Addition streamlit_pdf_viewer/__init__.py	Added allow_clickable_annotations_with_text_rendering: bool = False parameter to pdf_viewer() function signature; updated docstring; passed parameter to underlying component call.
Frontend Conditional Interactivity streamlit_pdf_viewer/frontend/src/PdfViewer.vue	Introduced allowClickableAnnotationsWithTextRendering flag; updated annotation interactivity logic to allow clicks when text rendering is enabled if the new flag is true; adjusted cursor style (pointer vs. text), pointer events (auto vs. none), and z-index (12 vs. 10) based on interactivity state.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change—adding a new parameter allow_clickable_annotations_with_text_rendering. It is clear, specific, and directly relates to the primary objective of the pull request.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 8eca42f and 7f75e4e.

📒 Files selected for processing (2)

• streamlit_pdf_viewer/__init__.py
• streamlit_pdf_viewer/frontend/src/PdfViewer.vue

🔇 Additional comments (8)

streamlit_pdf_viewer/frontend/src/PdfViewer.vue (5)

86-86: LGTM!

The prop extraction is correct and uses strict equality checking, consistent with the existing renderText pattern.

---

162-162: LGTM!

The logic correctly implements the feature:

• When render_text=false, annotations remain clickable (backward compatible)
• When render_text=true and new flag is false, annotations are non-interactive (backward compatible)
• When render_text=true and new flag is true, annotations become clickable (new feature)

---

163-164: LGTM!

The styling correctly reflects annotation interactivity with appropriate cursor and pointer-events values based on the computed annotationsClickable flag.

---

165-166: LGTM!

The z-index logic correctly positions annotations above the text layer (z-index 11) when the new flag is enabled, allowing clicks to reach the annotations instead of the text layer.

---

168-174: LGTM!

Conditionally attaching the click listener only when annotations are clickable is a good performance optimization and prevents unnecessary event handlers.

streamlit_pdf_viewer/__init__.py (3)

42-42: LGTM!

The parameter is correctly typed with a sensible default value of False, ensuring backward compatibility.

---

63-63: LGTM!

The docstring clearly explains the parameter's purpose and documents the trade-off that text selection will not work through annotation areas when enabled.

---

137-138: LGTM!

The parameter is correctly propagated to the component, completing the data flow from Python API to Vue frontend. The trailing comma on line 137 is good practice.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[anatolec]

Hey @lfoppiano ,
Thanks for this great library! I'm using it at inato for a medical document annotation tool where users need to:

1. Read and select text from PDFs (render_text=True)
2. Click on page regions to mark them as relevant

I discovered that these two features are currently mutually exclusive - when text rendering is enabled, annotations lose their click handlers and pointer events.

I understand the original design decision (prioritizing text selection over annotation clicks), so I've made this an opt-in feature that defaults to False to preserve backward compatibility.

I'm happy to adjust the implementation based on your feedback - whether that's the parameter name, the approach, or anything else. Let me know what you think!