Skip to content

Au-delà des bases : guide complet des boutons Streamlit

Updated on

Streamlit facilite la transformation de scripts Python en applications interactives, et les boutons sont souvent la première interaction attendue par les utilisateurs. Le widget st.button paraît minimaliste, mais il déverrouille des parcours qui vont du simple toggle aux actions multi-étapes. Ce guide remis à jour résume l’API moderne, clarifie les idées reçues et propose des modèles éprouvés pour concevoir des expériences fiables pilotées par des boutons.

À la recherche d’un composant d’analytique visuelle prêt à l’emploi pour vos projets Streamlit ?

PyGWalker (opens in a new tab) intègre une interface d’exploration proche de Tableau directement dans vos apps Streamlit. Regardez comment explorer vos données avec PyGWalker (opens in a new tab) ou consultez le guide d’intégration.

Comprendre st.button

Démarrage rapide

st.button affiche un élément cliquable et renvoie True pendant l’exécution du script qui suit immédiatement un clic. Ce booléen suffit pour la plupart des scénarios simples :

import streamlit as st
 
if st.button("Dire bonjour"):
    st.write("Bonjour, Streamlit !")

Streamlit relance l’intégralité du script à chaque changement de widget. En raison de ce modèle de relance, veillez à ce que le travail déclenché dans le bloc if soit idempotent ou protégé par de l’état supplémentaire.

Arguments clés à connaître

st.button accepte plusieurs arguments optionnels qui couvrent l’essentiel des besoins de personnalisation :

  • key : identifiant unique lorsque plusieurs boutons partagent le même libellé.
  • help : texte d’infobulle affiché au survol.
  • on_click : callback exécuté lorsque le bouton est pressé.
  • args / kwargs : arguments positionnels et nommés transmis au callback.
  • type : choisissez entre les styles "primary" et "secondary" pour respecter le thème Streamlit.
  • disabled : empêche l’interaction avec le bouton.
  • use_container_width : étend le bouton sur toute la largeur du conteneur parent.
def refresh_data(verbose: bool = False, limit: int | None = None) -> None:
    st.session_state["last_result"] = load_data(limit=limit)
    if verbose:
        st.success("Données actualisées")
 
st.button(
    "Actualiser les données",
    key="refresh",
    help="Récupérer les enregistrements les plus récents via l’API",
    type="primary",
    use_container_width=True,
    on_click=refresh_data,
    args=(True,),
    kwargs={"limit": 500},
)

Gérer les interactions au-delà de la valeur de retour

Exploiter les callbacks et l’état de session

Les callbacks s’exécutent après la collecte des changements de widgets par Streamlit. Ils sont donc parfaits pour encapsuler la logique et mettre à jour st.session_state :

import datetime as dt
import streamlit as st
 
if "last_clicked" not in st.session_state:
    st.session_state.last_clicked = None
 
 
def mark_timestamp() -> None:
    st.session_state.last_clicked = dt.datetime.now(dt.timezone.utc)
 
st.button("Enregistrer l’horodatage", on_click=mark_timestamp, type="primary")
 
st.write("Dernier clic :", st.session_state.last_clicked or "Pas encore")

Les callbacks maintiennent votre script principal déclaratif, évitent une forte imbrication de if et conservent l’état entre les relances.

Construire un comportement de type bascule

Les boutons ne restent pas enfoncés, mais en les combinant avec l’état de session, vous pouvez créer des interactions façon toggle :

import streamlit as st
 
st.session_state.setdefault("show_advanced", False)
 
if st.button("Afficher/masquer les options avancées"):
    st.session_state.show_advanced = not st.session_state.show_advanced
 
if st.session_state.show_advanced:
    st.info("La configuration avancée s’affiche ici.")

Pour des contrôles persistants (par exemple un interrupteur marche/arrêt), privilégiez des widgets comme st.checkbox ou st.toggle qui expriment mieux l’état.

Techniques de mise en page pour les boutons

Streamlit dispose les éléments dans l’ordre d’écriture, mais vous gardez la main sur la mise en page grâce aux conteneurs :

col1, col2 = st.columns(2)
with col1:
    st.button("Précédent", key="prev", type="secondary")
with col2:
    st.button("Suivant", key="next", type="primary", use_container_width=True)
 
with st.sidebar:
    st.button("Réinitialiser les filtres", key="reset")

Utilisez st.container() ou st.expander() pour regrouper des actions liées, et st.columns() pour aligner des boutons sur la même ligne sans recourir à du HTML brut.

Options de style et surcharges CSS

Streamlit limite volontairement la personnalisation directe pour conserver la cohérence, mais plusieurs choix restent possibles :

  • Préférez le preset intégré type="primary" pour mettre en avant une action et use_container_width=True pour des mises en page réactives.
  • Modifiez les couleurs par défaut via la configuration globale du thème (.streamlit/config.toml).
  • Pour un style spécifique, injectez du CSS ciblé avec st.markdown(..., unsafe_allow_html=True).
import streamlit as st
 
st.markdown(
    """
    <style>
    .custom-button button {
        background: linear-gradient(135deg, #005bbb, #00bcd4);
        color: white;
        border: 0;
        padding: 0.6rem 1.5rem;
        border-radius: 999px;
        transition: transform 0.1s ease-in-out;
    }
    .custom-button button:hover {
        transform: translateY(-1px);
    }
    </style>
    """,
    unsafe_allow_html=True,
)
 
with st.container():
    st.markdown('<div class="custom-button">', unsafe_allow_html=True)
    st.button("Bouton dégradé", key="custom")
    st.markdown("</div>", unsafe_allow_html=True)

Gardez les surcharges CSS ciblées : de gros blocs inline sont difficiles à maintenir et risquent de casser si Streamlit modifie ses classes internes.

Modèles pratiques

  • Divulgation progressive : associez un bouton et st.session_state pour afficher des champs ou du texte supplémentaire uniquement quand c’est nécessaire.
  • Étapes de traitement de données : désactivez des boutons (disabled=True) tant que des prérequis comme l’import d’un fichier ou un jeton d’authentification ne sont pas disponibles.
  • Flux de téléchargement : utilisez st.download_button quand il s’agit de proposer un fichier ; réservez st.button aux actions internes à l’application.

Conclusion

Les boutons structurent de nombreux parcours utilisateur dans Streamlit. En combinant la valeur booléenne retournée, l’API de callbacks et st.session_state, vous orchestrez des comportements complexes sans quitter le paradigme réactif. Appuyez-vous sur les primitives de mise en page pour l’alignement, recourez au CSS seulement si nécessaire, et considérez des widgets alternatifs lorsqu’un état persistant doit être explicite. Des boutons bien pensés rendent vos apps Streamlit rapides, intuitives et fiables.

Foire aux questions

Comment créer un bouton dans Streamlit ?

Utilisez st.button("Libellé"). La fonction renvoie True lors de l’exécution déclenchée par le clic, donc placez votre logique dans le bloc if correspondant ou fournissez un callback via on_click.

Comment positionner un bouton dans Streamlit ?

Encapsulez les widgets dans des primitives de mise en page telles que st.columns, st.container, st.sidebar ou st.expander. Ces conteneurs contrôlent l’emplacement sans recourir au HTML brut.

Comment créer des boutons radio dans Streamlit ?

Servez-vous de st.radio(label, options) pour présenter des choix mutuellement exclusifs. L’option sélectionnée est renvoyée immédiatement et peut être conservée dans st.session_state pour la suite du traitement.

Quels sont les inconvénients de Streamlit ?

Le modèle de relance de scripts simplifie le développement, mais peut sembler limitant lorsqu’on a besoin d’un contrôle très fin de la mise en page, de tâches longues en arrière-plan ou d’une personnalisation poussée du style. L’écosystème évolue cependant vite : nouveaux widgets, options de thème et aides autour de l’état de session réduisent progressivement ces limites.