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 etuse_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éservezst.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.