Streamlit Avatar

Common errors

• ModuleNotFoundError: No module named 'streamlit_avatar'

  cause The `streamlit-avatar` library is not installed in your current Python environment.
  fix Run `pip install streamlit-avatar` in your terminal to install the library.

• AttributeError: module 'streamlit' has no attribute 'st_avatar'

  cause You are attempting to import `st_avatar` directly from the `streamlit` module instead of its dedicated library.
  fix Change your import statement to `from streamlit_avatar import st_avatar`.

• Component Exception: Failed to render component streamlit_avatar.streamlit_avatar

  cause This generic error often indicates an issue with the parameters passed to `st_avatar`, such as an invalid `url` (e.g., a non-accessible image URL or a local file path not served by Streamlit), or potentially incorrect type/value for other styling parameters.
  fix Verify that the `url` provided is a valid, publicly accessible image URL. If using a local image, ensure it is served correctly by Streamlit or converted to a data URI. Double-check all parameters for correct types and values (e.g., `size` should be an int, colors valid strings).

Warnings

• gotcha The `is_image` parameter dictates whether the `url` content is treated as an image source or raw text. If `is_image=False`, the value of `url` is displayed as text directly, not interpreted as a URL to fetch a text-generated image.
  Fix: For text avatars (e.g., initials), set `is_image=False` and pass the desired text (e.g., 'JD') directly to the `url` parameter, rather than a URL that generates an image from text.
• gotcha Like all Streamlit components, `streamlit-avatar` must be run within a Streamlit application using `streamlit run your_app.py`. It will not render correctly if executed as a standard Python script.
  Fix: Always use `streamlit run <your_script_name>.py` from your terminal to execute Streamlit applications that use this component.
• gotcha Only specific styling parameters are exposed (size, border_radius, colors, font sizes). Custom CSS beyond these parameters is not directly supported by the component and may require using Streamlit's `st.markdown(unsafe_allow_html=True)` to inject broader styling rules, which can be more complex.
  Fix: Utilize the provided parameters for styling. For highly custom styles, explore Streamlit's `st.markdown(unsafe_allow_html=True)` with caution to target specific HTML elements rendered by the component, or consider contributing to the component's styling options.

Install

• pip install streamlit-avatar Install stable version

Imports

• st_avatar
  wrong:

  from streamlit import st_avatar

  correct:

  from streamlit_avatar import st_avatar

  The `st_avatar` function is part of the `streamlit_avatar` library, not directly from the core `streamlit` library.

Quickstart

This example demonstrates how to display both an image-based avatar from a URL and a text-based avatar (e.g., initials) using the `streamlit_avatar` component. It showcases setting size, border styles, and click actions.

import streamlit as st
from streamlit_avatar import st_avatar

st.set_page_config(layout="wide")

st.title("Streamlit Avatar Example")

# Example 1: Image avatar from a URL
st.header("1. Image Avatar")
st.markdown("Displays an image from a URL. Click to open GitHub.")
st_avatar(
    url="https://avatars.githubusercontent.com/u/84214537?v=4",
    size=80,
    border_radius=50,
    border_color="#007BFF",
    border_hover_color="#0056B3",
    open_url_on_click="https://github.com/ppspps824"
)

# Example 2: Text avatar (initials)
st.header("2. Text Avatar (Initials)")
st.markdown("Displays text (e.g., initials) by setting `is_image=False`.")
st_avatar(
    url="SA", # The text to display
    size=60,
    is_image=False,
    title_font_size=24,
    title_color="#FFF",
    border_radius=10,
    border_color="#28A745",
    border_hover_color="#218838"
)

st.write("---")
st.write("Avatars demonstrated above.")