IUT
Intermédiaire

Les composants essentiels

Streamlit fournit des composants pour afficher du contenu et interagir avec l'utilisateur. Cette page couvre quatre familles : texte, métriques, tableaux et widgets.

Affichage de texte et structure

Streamlit propose une hiérarchie de composants texte :

ComposantUsage
st.title()Titre principal de la page
st.header()Titre de section
st.subheader()Titre de sous-section
st.write()Polyvalent : strings, DataFrames, dicts, figures
st.markdown()Markdown complet (gras, listes, liens)
st.caption()Texte secondaire, annotations
st.code()Bloc de code avec coloration syntaxique

st.write() : le composant passe-partout

st.write() détecte le type de l'argument et s'adapte :

  • Une chaîne de caractères est affichée comme du texte (avec support Markdown)
  • Un DataFrame pandas est affiché comme un tableau interactif
  • Un dictionnaire est affiché comme du JSON formaté
  • Une figure Plotly est affichée comme un graphique interactif
python
import streamlit as st
import pandas as pd

st.write("Bonjour, voici un tableau :")
st.write(pd.DataFrame({"col1": [1, 2, 3], "col2": [4, 5, 6]}))
st.write({"clé": "valeur", "nombre": 42})

Composants explicites vs st.write()

On préfère les composants explicites (st.dataframe(), st.markdown()) pour plus de contrôle sur le rendu. st.write() est pratique pour le prototypage.

Que se passe-t-il quand on passe un dictionnaire Python à st.write() ?

Métriques et KPI cards

st.metric() affiche un indicateur clé (KPI) : un label, une valeur principale et une variation optionnelle.

python
st.metric(
    label="Chiffre d'affaires",
    value="2 845 600 €",
    delta="+12.3% vs an dernier"
)

Le paramètre delta est automatiquement coloré : vert si positif, rouge si négatif. Pour inverser cette logique (un delta négatif est une bonne nouvelle, par exemple un taux d'erreur qui baisse), utilisez delta_color="inverse".

Aligner plusieurs métriques

Pour aligner plusieurs métriques sur une même ligne, on utilise st.columns() :

python
col1, col2, col3 = st.columns(3)

with col1:
    st.metric("CA Total", "2.8M €", "+12%")
with col2:
    st.metric("Nb ventes", "15 420", "+8%")
with col3:
    st.metric("Panier moyen", "184 €", "-2%", delta_color="inverse")

delta_color

Les valeurs possibles pour delta_color sont : "normal" (vert positif, rouge négatif — par défaut), "inverse" (rouge positif, vert négatif) et "off" (pas de coloration).

Tableaux de données

Deux composants pour afficher des données tabulaires :

  • st.dataframe() : tableau interactif — tri par colonne au clic, redimensionnable, scroll. Accepte un DataFrame pandas, une liste de dicts, un dict. C'est le choix par défaut.
  • st.table() : tableau statique, rendu HTML simple. Utile uniquement pour de petits tableaux de référence qui n'ont pas besoin d'interactivité.

Options de st.dataframe()

python
st.dataframe(
    df,
    use_container_width=True,   # occupe toute la largeur disponible
    height=400,                  # hauteur fixe avec scroll vertical
    column_config={
        "chiffre_affaires": st.column_config.NumberColumn(
            "CA (€)",
            format="%.2f €"
        ),
        "progression": st.column_config.ProgressColumn(
            "Progression",
            min_value=0,
            max_value=100
        )
    }
)

column_config

column_config (depuis Streamlit 1.22) personnalise l'affichage de chaque colonne sans modifier le DataFrame : format monétaire, barres de progression, icônes, liens cliquables.

Quelle est la différence principale entre st.dataframe() et st.table() ?

Widgets d'interaction

Chaque widget est une fonction Python qui retourne une valeur utilisable immédiatement dans le script.

WidgetRetourneUsage typique
st.selectbox(label, options)stringSélection d'une catégorie
st.multiselect(label, options)listSélection multiple
st.slider(label, min, max, value)int ou floatPlage numérique, années
st.text_input(label)stringRecherche textuelle
st.date_input(label)dateSélection de période
st.checkbox(label)boolOption on/off
st.button(label)boolAction ponctuelle

Pattern : widgets en haut, affichages en bas

La valeur retournée par un widget est disponible dès la ligne suivante. On place les widgets en haut du script et les affichages en bas :

python
# Widgets — haut du script
region = st.selectbox("Région", ["Toutes", "IDF", "PACA", "ARA"])
annee = st.slider("Année", 2020, 2024, 2024)

# Utilisation immédiate des valeurs
data = repository.get_ventes(
    region=region if region != "Toutes" else None,
    annee=annee
)
st.dataframe(data)

Comportement particulier de st.button()

Attention à st.button()

st.button() retourne True uniquement au moment du clic, puis revient à False au re-run suivant. Il ne maintient pas un état « pressé ». Pour un comportement toggle (on/off), utilisez st.checkbox() ou st.session_state.

python
# Ce code affiche "Bouton cliqué !" seulement pendant le re-run
# déclenché par le clic — puis disparaît
if st.button("Cliquer"):
    st.write("Bouton cliqué !")

Que retourne st.button('Valider') après le premier re-run suivant le clic ?

À retenir

Points clés

  • st.write() est polyvalent mais les composants explicites offrent plus de contrôle
  • st.metric() avec delta et delta_color est idéal pour les KPI cards
  • st.dataframe() est interactif (tri, scroll), st.table() est statique
  • Chaque widget retourne une valeur utilisable immédiatement
  • st.button() ne maintient pas d'état — il retourne True uniquement au moment du clic

Streamlit API Reference — Display elements

Documentation officielle des composants d'affichage

Documentation

Streamlit Widget Reference

Documentation officielle de tous les widgets d'interaction

Documentation