# st_pptx_viewer
A powerful and configurable Streamlit component for rendering PowerPoint presentations using the PptxViewJS library.
## Features
- 🎨 **Fully Customizable**: Control canvas size, toolbar position, colors, and more
- ⌨️ **Keyboard Navigation**: Arrow keys and Page Up/Down support
- 📱 **Responsive Design**: Automatically adapts to slide aspect ratios
- 🎯 **Easy Integration**: Simple API with sensible defaults
- 🔧 **Flexible Configuration**: Dataclass-based configuration for type safety
- ⛶ **Fullscreen Mode**: Optional fullscreen viewing
- 🎭 **Custom Styling**: Add your own CSS for complete control
## Installation
### From Source
The module uses CDN-hosted PptxViewJS by default, so no build step is required!
```bash
pip install -e ./st_pptx_viewer
```
Or use the automated installer:
```bash
cd st_pptx_viewer
./install.sh
```
### From PyPI (when published)
```bash
pip install st-pptx-viewer
```
## Quick Start
### Basic Usage
```python
import streamlit as st
from st_pptx_viewer import pptx_viewer
st.title("PowerPoint Viewer")
uploaded_file = st.file_uploader("Upload a PPTX file", type=["pptx"])
if uploaded_file:
pptx_viewer(uploaded_file)
```
### With Configuration
```python
import streamlit as st
from st_pptx_viewer import pptx_viewer, PptxViewerConfig
# Create custom configuration
config = PptxViewerConfig(
width=1200,
show_toolbar=True,
show_slide_counter=True,
enable_keyboard=True,
toolbar_position='bottom',
enable_fullscreen=True,
canvas_border='2px solid #0066cc',
canvas_background='#f5f5f5',
)
uploaded_file = st.file_uploader("Upload a PPTX file", type=["pptx"])
if uploaded_file:
pptx_viewer(uploaded_file, config=config)
```
### From File Path
```python
from pathlib import Path
from st_pptx_viewer import pptx_viewer
# Load from file path
pptx_path = Path("./presentations/demo.pptx")
pptx_viewer(pptx_path)
```
## Configuration Options
The `PptxViewerConfig` dataclass provides the following options:
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `width` | int | 960 | Canvas width in pixels |
| `height` | int\|None | None | Canvas height (auto-calculated from aspect ratio if None) |
| `show_toolbar` | bool | True | Show navigation toolbar |
| `show_slide_counter` | bool | True | Show "Slide X / Y" counter |
| `initial_slide` | int | 0 | Initial slide index (0-based) |
| `enable_keyboard` | bool | True | Enable keyboard navigation |
| `toolbar_position` | str | 'top' | Toolbar position: 'top' or 'bottom' |
| `canvas_border` | str | '1px solid #ddd' | CSS border style for canvas |
| `canvas_background` | str | '#fff' | Background color for canvas |
| `canvas_border_radius` | int | 4 | Border radius in pixels |
| `component_height` | int\|None | None | Total component height (auto-calculated if None) |
| `custom_css` | str | '' | Additional custom CSS styles |
| `pptxviewjs_path` | str\|Path\|None | None | Custom path to PptxViewJS.min.js (uses CDN if None) |
| `enable_fullscreen` | bool | False | Show fullscreen button |
| `toolbar_style` | dict | {} | Custom CSS styles for toolbar |
## Advanced Examples
### Custom Styling
```python
from st_pptx_viewer import pptx_viewer, PptxViewerConfig
config = PptxViewerConfig(
width=1000,
toolbar_style={
'background': 'linear-gradient(to right, #667eea, #764ba2)',
'color': 'white',
},
custom_css="""
.toolbar button {
background: white !important;
color: #667eea !important;
font-weight: bold;
}
.toolbar button:hover {
background: #f0f0f0 !important;
}
""",
canvas_border='3px solid #667eea',
canvas_border_radius=12,
)
pptx_viewer(uploaded_file, config=config)
```
### Multiple Presentations
```python
import streamlit as st
from st_pptx_viewer import pptx_viewer, PptxViewerConfig
st.title("Compare Presentations")
col1, col2 = st.columns(2)
with col1:
st.subheader("Presentation A")
file_a = st.file_uploader("Upload A", type=["pptx"], key="a")
if file_a:
config = PptxViewerConfig(width=500)
pptx_viewer(file_a, config=config, key="viewer_a")
with col2:
st.subheader("Presentation B")
file_b = st.file_uploader("Upload B", type=["pptx"], key="b")
if file_b:
config = PptxViewerConfig(width=500)
pptx_viewer(file_b, config=config, key="viewer_b")
```
### Starting at Specific Slide
```python
config = PptxViewerConfig(
initial_slide=5, # Start at slide 6 (0-based index)
width=1000,
)
pptx_viewer(uploaded_file, config=config)
```
### Minimal Viewer (No Toolbar)
```python
config = PptxViewerConfig(
show_toolbar=False,
width=800,
canvas_border='none',
)
pptx_viewer(uploaded_file, config=config)
```
## Keyboard Shortcuts
When `enable_keyboard=True` (default), the following shortcuts are available:
- **Arrow Left** or **Page Up**: Previous slide
- **Arrow Right**, **Page Down**, or **Space**: Next slide
## Requirements
- Python >= 3.8
- Streamlit >= 1.0.0
- Internet connection (for CDN-hosted PptxViewJS)
## Troubleshooting
### CDN Loading Issues
The module uses CDN-hosted PptxViewJS by default. If you have connectivity issues:
1. Check your internet connection
2. Check if CDN is accessible: https://cdn.jsdelivr.net/npm/pptxviewjs/dist/PptxViewJS.min.js
**Using a local bundle instead:**
```python
config = PptxViewerConfig(
pptxviewjs_path="/path/to/PptxViewJS.min.js"
)
```
### Presentation Not Rendering
- Ensure the PPTX file is valid and not corrupted
- Check browser console for JavaScript errors
- Try with a simpler presentation first
### Layout Issues
- Adjust `width` and `height` in configuration
- Use `component_height` to control total iframe height
- Add custom CSS via `custom_css` parameter
## API Reference
### `pptx_viewer(pptx_file, config=None, key=None)`
Main function to render a PPTX file in Streamlit.
**Parameters:**
- `pptx_file` (bytes | BinaryIO | str | Path): PPTX file as bytes, file-like object, or path
- `config` (PptxViewerConfig | None): Configuration options
- `key` (str | None): Unique component key for Streamlit
**Returns:** None
### `PptxViewerConfig`
Dataclass for configuration options. See Configuration Options section above.
## License
This module is part of the PptxViewJS project. See the main project LICENSE file for details.
## Contributing
Contributions are welcome! Please see the main project repository for contribution guidelines.
## Related Projects
- [PptxViewJS](https://github.com/sdafa123/js-slide-viewer) - The underlying JavaScript library
- [Streamlit](https://streamlit.io) - The web framework this component is built for
## Support
For issues and questions:
- GitHub Issues: [Report a bug](https://github.com/sdafa123/js-slide-viewer/issues)
- Documentation: See examples in the `examples/` directory
## Changelog
### v1.0.0
- Initial release
- Full configuration support
- Keyboard navigation
- Fullscreen mode
- Custom styling options
Raw data
{
"_id": null,
"home_page": "https://github.com/sdafa123/js-slide-viewer",
"name": "st-pptx-viewer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "streamlit, pptx, powerpoint, viewer, presentation, component",
"author": "PptxViewJS Contributors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/2d/6e/9046d75ee3104e207c24a028198e6d394e307f145655686e2c9cd7901b3f/st_pptx_viewer-1.0.0.tar.gz",
"platform": null,
"description": "# st_pptx_viewer\n\nA powerful and configurable Streamlit component for rendering PowerPoint presentations using the PptxViewJS library.\n\n## Features\n\n- \ud83c\udfa8 **Fully Customizable**: Control canvas size, toolbar position, colors, and more\n- \u2328\ufe0f **Keyboard Navigation**: Arrow keys and Page Up/Down support\n- \ud83d\udcf1 **Responsive Design**: Automatically adapts to slide aspect ratios\n- \ud83c\udfaf **Easy Integration**: Simple API with sensible defaults\n- \ud83d\udd27 **Flexible Configuration**: Dataclass-based configuration for type safety\n- \u26f6 **Fullscreen Mode**: Optional fullscreen viewing\n- \ud83c\udfad **Custom Styling**: Add your own CSS for complete control\n\n## Installation\n\n### From Source\n\nThe module uses CDN-hosted PptxViewJS by default, so no build step is required!\n\n```bash\npip install -e ./st_pptx_viewer\n```\n\nOr use the automated installer:\n```bash\ncd st_pptx_viewer\n./install.sh\n```\n\n### From PyPI (when published)\n```bash\npip install st-pptx-viewer\n```\n\n## Quick Start\n\n### Basic Usage\n\n```python\nimport streamlit as st\nfrom st_pptx_viewer import pptx_viewer\n\nst.title(\"PowerPoint Viewer\")\n\nuploaded_file = st.file_uploader(\"Upload a PPTX file\", type=[\"pptx\"])\nif uploaded_file:\n pptx_viewer(uploaded_file)\n```\n\n### With Configuration\n\n```python\nimport streamlit as st\nfrom st_pptx_viewer import pptx_viewer, PptxViewerConfig\n\n# Create custom configuration\nconfig = PptxViewerConfig(\n width=1200,\n show_toolbar=True,\n show_slide_counter=True,\n enable_keyboard=True,\n toolbar_position='bottom',\n enable_fullscreen=True,\n canvas_border='2px solid #0066cc',\n canvas_background='#f5f5f5',\n)\n\nuploaded_file = st.file_uploader(\"Upload a PPTX file\", type=[\"pptx\"])\nif uploaded_file:\n pptx_viewer(uploaded_file, config=config)\n```\n\n### From File Path\n\n```python\nfrom pathlib import Path\nfrom st_pptx_viewer import pptx_viewer\n\n# Load from file path\npptx_path = Path(\"./presentations/demo.pptx\")\npptx_viewer(pptx_path)\n```\n\n## Configuration Options\n\nThe `PptxViewerConfig` dataclass provides the following options:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `width` | int | 960 | Canvas width in pixels |\n| `height` | int\\|None | None | Canvas height (auto-calculated from aspect ratio if None) |\n| `show_toolbar` | bool | True | Show navigation toolbar |\n| `show_slide_counter` | bool | True | Show \"Slide X / Y\" counter |\n| `initial_slide` | int | 0 | Initial slide index (0-based) |\n| `enable_keyboard` | bool | True | Enable keyboard navigation |\n| `toolbar_position` | str | 'top' | Toolbar position: 'top' or 'bottom' |\n| `canvas_border` | str | '1px solid #ddd' | CSS border style for canvas |\n| `canvas_background` | str | '#fff' | Background color for canvas |\n| `canvas_border_radius` | int | 4 | Border radius in pixels |\n| `component_height` | int\\|None | None | Total component height (auto-calculated if None) |\n| `custom_css` | str | '' | Additional custom CSS styles |\n| `pptxviewjs_path` | str\\|Path\\|None | None | Custom path to PptxViewJS.min.js (uses CDN if None) |\n| `enable_fullscreen` | bool | False | Show fullscreen button |\n| `toolbar_style` | dict | {} | Custom CSS styles for toolbar |\n\n## Advanced Examples\n\n### Custom Styling\n\n```python\nfrom st_pptx_viewer import pptx_viewer, PptxViewerConfig\n\nconfig = PptxViewerConfig(\n width=1000,\n toolbar_style={\n 'background': 'linear-gradient(to right, #667eea, #764ba2)',\n 'color': 'white',\n },\n custom_css=\"\"\"\n .toolbar button {\n background: white !important;\n color: #667eea !important;\n font-weight: bold;\n }\n .toolbar button:hover {\n background: #f0f0f0 !important;\n }\n \"\"\",\n canvas_border='3px solid #667eea',\n canvas_border_radius=12,\n)\n\npptx_viewer(uploaded_file, config=config)\n```\n\n### Multiple Presentations\n\n```python\nimport streamlit as st\nfrom st_pptx_viewer import pptx_viewer, PptxViewerConfig\n\nst.title(\"Compare Presentations\")\n\ncol1, col2 = st.columns(2)\n\nwith col1:\n st.subheader(\"Presentation A\")\n file_a = st.file_uploader(\"Upload A\", type=[\"pptx\"], key=\"a\")\n if file_a:\n config = PptxViewerConfig(width=500)\n pptx_viewer(file_a, config=config, key=\"viewer_a\")\n\nwith col2:\n st.subheader(\"Presentation B\")\n file_b = st.file_uploader(\"Upload B\", type=[\"pptx\"], key=\"b\")\n if file_b:\n config = PptxViewerConfig(width=500)\n pptx_viewer(file_b, config=config, key=\"viewer_b\")\n```\n\n### Starting at Specific Slide\n\n```python\nconfig = PptxViewerConfig(\n initial_slide=5, # Start at slide 6 (0-based index)\n width=1000,\n)\npptx_viewer(uploaded_file, config=config)\n```\n\n### Minimal Viewer (No Toolbar)\n\n```python\nconfig = PptxViewerConfig(\n show_toolbar=False,\n width=800,\n canvas_border='none',\n)\npptx_viewer(uploaded_file, config=config)\n```\n\n## Keyboard Shortcuts\n\nWhen `enable_keyboard=True` (default), the following shortcuts are available:\n\n- **Arrow Left** or **Page Up**: Previous slide\n- **Arrow Right**, **Page Down**, or **Space**: Next slide\n\n## Requirements\n\n- Python >= 3.8\n- Streamlit >= 1.0.0\n- Internet connection (for CDN-hosted PptxViewJS)\n\n## Troubleshooting\n\n### CDN Loading Issues\n\nThe module uses CDN-hosted PptxViewJS by default. If you have connectivity issues:\n\n1. Check your internet connection\n2. Check if CDN is accessible: https://cdn.jsdelivr.net/npm/pptxviewjs/dist/PptxViewJS.min.js\n\n**Using a local bundle instead:**\n```python\nconfig = PptxViewerConfig(\n pptxviewjs_path=\"/path/to/PptxViewJS.min.js\"\n)\n```\n\n### Presentation Not Rendering\n\n- Ensure the PPTX file is valid and not corrupted\n- Check browser console for JavaScript errors\n- Try with a simpler presentation first\n\n### Layout Issues\n\n- Adjust `width` and `height` in configuration\n- Use `component_height` to control total iframe height\n- Add custom CSS via `custom_css` parameter\n\n## API Reference\n\n### `pptx_viewer(pptx_file, config=None, key=None)`\n\nMain function to render a PPTX file in Streamlit.\n\n**Parameters:**\n- `pptx_file` (bytes | BinaryIO | str | Path): PPTX file as bytes, file-like object, or path\n- `config` (PptxViewerConfig | None): Configuration options\n- `key` (str | None): Unique component key for Streamlit\n\n**Returns:** None\n\n### `PptxViewerConfig`\n\nDataclass for configuration options. See Configuration Options section above.\n\n## License\n\nThis module is part of the PptxViewJS project. See the main project LICENSE file for details.\n\n## Contributing\n\nContributions are welcome! Please see the main project repository for contribution guidelines.\n\n## Related Projects\n\n- [PptxViewJS](https://github.com/sdafa123/js-slide-viewer) - The underlying JavaScript library\n- [Streamlit](https://streamlit.io) - The web framework this component is built for\n\n## Support\n\nFor issues and questions:\n- GitHub Issues: [Report a bug](https://github.com/sdafa123/js-slide-viewer/issues)\n- Documentation: See examples in the `examples/` directory\n\n## Changelog\n\n### v1.0.0\n- Initial release\n- Full configuration support\n- Keyboard navigation\n- Fullscreen mode\n- Custom styling options\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Streamlit component for rendering PowerPoint presentations using PptxViewJS",
"version": "1.0.0",
"project_urls": {
"Bug Reports": "https://github.com/sdafa123/js-slide-viewer/issues",
"Documentation": "https://github.com/sdafa123/js-slide-viewer/blob/main/st_pptx_viewer/README.md",
"Homepage": "https://github.com/sdafa123/js-slide-viewer",
"Repository": "https://github.com/sdafa123/js-slide-viewer"
},
"split_keywords": [
"streamlit",
" pptx",
" powerpoint",
" viewer",
" presentation",
" component"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4ee455c92776f918312048bb9044660ac1f3c3fc9102ec0cac53d1a6cb55d673",
"md5": "363aec7959d9a22e6d73b11054ce39df",
"sha256": "ca5db17a7ea08efd7a5d544b8def136bc42d04b7c7c8126ce4b070efa0c7584f"
},
"downloads": -1,
"filename": "st_pptx_viewer-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "363aec7959d9a22e6d73b11054ce39df",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 11132,
"upload_time": "2025-10-14T17:39:52",
"upload_time_iso_8601": "2025-10-14T17:39:52.237605Z",
"url": "https://files.pythonhosted.org/packages/4e/e4/55c92776f918312048bb9044660ac1f3c3fc9102ec0cac53d1a6cb55d673/st_pptx_viewer-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2d6e9046d75ee3104e207c24a028198e6d394e307f145655686e2c9cd7901b3f",
"md5": "ddc726ed8b846144266e79d59beafdee",
"sha256": "1204e8b434986e5607e85e3ec7f0727fb9cc24f0136477ca83a9b3ef1a5121ce"
},
"downloads": -1,
"filename": "st_pptx_viewer-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "ddc726ed8b846144266e79d59beafdee",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 35511,
"upload_time": "2025-10-14T17:39:53",
"upload_time_iso_8601": "2025-10-14T17:39:53.302812Z",
"url": "https://files.pythonhosted.org/packages/2d/6e/9046d75ee3104e207c24a028198e6d394e307f145655686e2c9cd7901b3f/st_pptx_viewer-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-14 17:39:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sdafa123",
"github_project": "js-slide-viewer",
"github_not_found": true,
"lcname": "st-pptx-viewer"
}
JSON
