Implementing Extra
Developmentimplementing-extraImplementing Extra is an Agent Skill for development published in the arnaudmiribel/streamlit-extras repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Guides implementation of new streamlit-extras from spec to verification. Use when adding a new extra, creating a Streamlit component, or when the user says "implement extra", "new extra", or "add extra".
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/arnaudmiribel/streamlit-extras/blob/HEAD/.claude/skills/implementing-extra/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/implementing-extra, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Implementing a New Extra
Multi-step workflow for adding new extras to streamlit-extras. Always read and follow src/streamlit_extras/AGENTS.md first.
Workflow Checklist
Copy this checklist and track progress:
Implementation Progress:
- [ ] Step 1: Write product spec in work-tmp/
- [ ] Step 2: Decide component type
- [ ] Step 3: Implement the extra
- [ ] Step 4: Verify implementation
Step 1: Write Product Spec
Create a spec in work-tmp/<extra_name>-spec.md before coding.
Use the template in references/spec-template.md which follows Streamlit's product spec format:
- Summary - 2-3 sentences describing the extra
- Problem - Motivation, user requests, pain points
- Proposal - API design, behavior, examples
- Out of Scope - Features not included in v1
Follow the Streamlit API design principles from: https://raw.githubusercontent.com/streamlit/streamlit/refs/heads/develop/specs/AGENTS.md
Step 2: Decide Component Type
Read the decision table in src/streamlit_extras/AGENTS.md under "Choosing a Component Type".
Quick reference:
| Requirement | Type |
|---|---|
| No UI/frontend needed | pure python |
| HTML/CSS only | st.html |
| Markdown + HTML | st.markdown(unsafe_allow_html) |
| URL in iframe | components v1: iframe |
| Full HTML in iframe | components v1: html |
| JavaScript execution (simple) | components v2: inline |
| Basic JS/HTML/CSS UI | components v2: inline or static assets |
| Complex UI / React / npm deps | components v2: react |
For CCv2 components, use the /building-streamlit-custom-components-v2 skill.
Step 3: Implement
Create src/streamlit_extras/<extra_name>/__init__.py with:
- Main function decorated with
@extra - Example function for the gallery
- Required metadata (see references/metadata.md)
Template:
from streamlit_extras import extra
@extra
def my_extra(param: str, *, key: str | None = None) -> None:
"""One-line description.
Args:
param: Description.
key: Unique key for this instance.
"""
...
def example() -> None:
"""Example for gallery."""
my_extra("demo")
__title__ = "My Extra"
__desc__ = "Short description of what it does."
__icon__ = "..." # Single emoji
__author__ = "Your Name"
__examples__ = [example]
Step 4: Verify
Run these checks before committing:
# Linting and formatting
uv run ruff check --fix
uv run ruff format
# Type checking
uv run mypy
uv run ty check
# Tests (validates metadata)
uv run pytest
For CCv2 React components, also verify the build:
# Build wheel (compiles React frontends via hatch hook)
uv build
# Check build artifacts exist
ls src/streamlit_extras/<extra_name>/frontend/build/
CRITICAL: Never commit build artifacts or lock files. The following are gitignored and must NOT be git add-ed:
frontend/build/— built by CI before publishing; never commit locally-built JS bundlesfrontend/package-lock.json— lock files are not needed in the repofrontend/node_modules/— never commit dependencies
If you accidentally staged them, remove with git rm --cached <path>.
References
- Spec template: references/spec-template.md
- Metadata attributes: references/metadata.md
- API design principles: https://raw.githubusercontent.com/streamlit/streamlit/refs/heads/develop/specs/AGENTS.md
- CCv2 components: Use
/building-streamlit-custom-components-v2skill - Extras overview:
src/streamlit_extras/AGENTS.md