Install & Compatibility
Where this runs
tested against v1.0.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 1.759s · 448.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 15.6s · import 0.992s · 417MB
436MB installed
● package 436MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
card
✓ from streamlit_card import card
This quickstart demonstrates how to create two types of cards: one that redirects to a URL upon click, and another that triggers an internal Streamlit callback function. It also shows basic styling customization.
import streamlit as st
from streamlit_card import card
st.set_page_config(layout='wide')
st.title("My Streamlit Cards Demo")
# Example 1: Basic Clickable Card with URL
has_clicked_github = card(
title="Visit GitHub",
text="Explore the source code of streamlit-card.",
image="https://placekitten.com/200/300",
url="https://github.com/gamcoh/st-card",
styles={
"card": {
"width": "300px",
"height": "200px",
"border-radius": "10px",
"box-shadow": "0 0 10px rgba(0,0,0,0.2)"
}
}
)
if has_clicked_github:
st.write("Redirecting to GitHub...")
# Example 2: Card with internal callback for interaction
def handle_card_click():
st.session_state['card_message'] = 'Card was clicked! You can perform actions here.'
if 'card_message' not in st.session_state:
st.session_state['card_message'] = 'Click the card below!'
has_clicked_callback = card(
title="Interactive Card",
text="Click me to trigger an action within the app.",
image="https://placebear.com/200/300",
on_click=handle_card_click,
styles={
"card": {
"width": "300px",
"height": "200px",
"border-radius": "10px",
"background-color": "#f0f2f6",
"box-shadow": "0 0 10px rgba(0,0,0,0.1)"
}
}
)
st.write(st.session_state['card_message'])
Debug
Known issues
gotchaWhen using local images, `streamlit_card` expects the image data as a base64 encoded string, not a direct file path. This is a common pattern for Streamlit custom components.fixUse `base64.b64encode(f.read()).decode('utf-8')` to encode local image files. For example:
```python
import base64
with open('path/to/your/image.png', 'rb') as f:
data = f.read()
encoded_image = 'data:image/png;base64,' + base64.b64encode(data).decode('utf-8')
card(..., image=encoded_image, ...)
``` affects: All versions
gotchaBe aware of naming conflicts and similar libraries. `streamlit-card` is a distinct component. `streamlit-extras` also contains a 'card' module (`from streamlit_extras.card import card`), and `streamlit-swipecards` offers swipeable card functionality. Ensure you import from the correct library to avoid unexpected behavior.fixExplicitly use `from streamlit_card import card` to import this specific component. If using multiple card components, use aliasing like `from streamlit_card import card as st_card` to prevent name clashes.
affects: All versions
gotchaFor simple clickable images that navigate to a URL, Streamlit's native `st.image` function with the `link` parameter might be a simpler alternative. `streamlit-card` offers more extensive styling and callback options beyond basic image linking.fixConsider `st.image(image_source, caption='Click me', link='https://example.com/')` for basic clickable images. Use `streamlit-card` when you need complex layouts, text overlays, custom styling, or in-app Python callbacks on click.
affects: Streamlit v1.1.0 and above
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'streamlit_card'
The 'streamlit-card' library has not been installed in the active Python environment.
fixpip install streamlit-card
TypeError: 'NoneType' object is not callable
The 'on_click' parameter received the result of a function call (e.g., 'my_function()') instead of a callable function object (e.g., 'my_function' or 'lambda: my_function()').
fixPass the function object directly or a lambda that calls it, without parentheses if it takes no arguments: 'on_click=my_function' or 'on_click=lambda: my_function()'.
StreamlitAPIException: Every element must have a unique key. Duplicate key 'XYZ' found.
Multiple 'card' components in a Streamlit application are rendered without unique 'key' arguments, which is required by Streamlit for interactive components.
fixEnsure each 'card' call has a unique 'key' string, especially when used inside loops or conditional blocks. Example: 'card(..., key=f"my_card_{i}")'. AttributeError: module 'streamlit_card' has no attribute 'Card'
The 'streamlit-card' library provides a function named 'card', but the user attempted to call it as a class 'Card' or tried to access a non-existent attribute named 'Card'.
fixCall the component as a function 'card' instead of a class 'Card': 'from streamlit_card import card' then 'card(...)'.
Upgrade
Version history
1.0.2latest on PyPI · released May 10, 2024
Audit
Dependencies
streamlitrequiredThis is a custom component designed to extend Streamlit's functionality.