Títulos y encabezados con st.title, st.header y st.subheader

Jerarquía de encabezados en Streamlit

Los elementos de texto son los componentes más básicos de cualquier aplicación Streamlit. Antes de añadir gráficos, widgets o tablas, es necesario estructurar la interfaz con una jerarquía visual clara que guíe al usuario a través del contenido.

Streamlit proporciona cinco niveles de texto estructural que se mapean directamente a la jerarquía de encabezados HTML (h1 a h6):

import streamlit as st

st.title("Título principal de la aplicación")      # H1 — uno por página
st.header("Sección principal")                      # H2
st.subheader("Subsección o grupo de métricas")     # H3
st.text("Texto plano sin formato, tipografía monoespaciada")
st.caption("Nota al pie, descripción breve, texto auxiliar")

Cuándo usar cada uno:

• st.title: Nombre de la aplicación o del dashboard. Debe haber uno solo por página.
• st.header: Marca el inicio de una sección importante (por ejemplo, "Análisis de ventas", "Configuración").
• st.subheader: Divide secciones en subsecciones (por ejemplo, "Filtros", "Resultados", "Exportar").
• st.text: Texto monoespaciado, útil para mostrar datos preformateados o logs.
• st.caption: Texto pequeño para notas al pie, leyendas de imágenes o información secundaria.

La correcta aplicación de esta jerarquía no es solo una cuestión estética: los lectores de pantalla y herramientas de accesibilidad utilizan la estructura de encabezados para permitir la navegación por secciones, y los motores de búsqueda la interpretan para entender la organización del contenido.

flowchart TD
    A[Página Streamlit] --> B[st.title H1 único]
    B --> C[st.header H2 sección principal]
    C --> D[st.subheader H3 subsección]
    D --> E[st.text texto plano monoespaciado]
    D --> F[st.caption nota auxiliar pequena]
    A --> G[st.write fallback inteligente]
    G --> H[Detecta dataframe imagen markdown]
    A --> I[st.divider separador visual]
    A --> J[st.badge etiqueta de estado]
    B --> K[Accesibilidad lectores pantalla]
    K --> L[SEO interpretación estructura]

Parámetros comunes de los encabezados

Todos los elementos de texto aceptan el parámetro anchor para crear un ID HTML al que enlazar, permitiendo crear enlaces de anclaje dentro de la misma página:

st.header("Resultados del análisis", anchor="resultados")
# Genera un enlace del tipo: http://localhost:8501/#resultados

El parámetro divider añade una línea de separación debajo del encabezado, útil para marcar visualmente el inicio de secciones:

st.header("Panel de control", divider="rainbow")
# Opciones: True/False, "blue", "green", "orange", "red", "violet", "gray", "rainbow"

st.subheader("Métricas de rendimiento", divider="blue")

st.caption: texto auxiliar y contexto

st.caption es ideal para añadir contexto secundario sin restar protagonismo al contenido principal:

import streamlit as st
import pandas as pd

st.title("Dataset de iris")
st.caption("Fuente: UCI Machine Learning Repository. Último acceso: marzo 2026.")

df = pd.read_csv("iris.csv")
st.dataframe(df)
st.caption(f"Mostrando {len(df)} registros. Columnas: {', '.join(df.columns)}")

st.badge: etiquetas visuales

st.badge muestra etiquetas visuales coloreadas que funcionan como indicadores de estado, categorías o alertas rápidas. Cada badge se renderiza como un pequeño rectángulo con fondo de color y texto blanco, similar a las etiquetas que se ven en repositorios de GitHub o documentación técnica:

import streamlit as st

st.badge("Nuevo", color="green")
st.badge("Deprecated", color="red")
st.badge("Beta", color="orange")
st.badge("v1.40.0", color="blue")
st.badge("Experimental", color="violet")

Los badges son especialmente útiles en documentación técnica dentro de la app para señalar el estado de funcionalidades o versiones.

st.divider y st.space: separación visual

import streamlit as st

st.header("Sección A")
st.write("Contenido de la sección A.")

st.divider()  # Línea horizontal de separación

st.header("Sección B")
st.write("Contenido de la sección B.")

st.space(height=2)  # Espacio vertical en unidades relativas

Ejemplo completo: dashboard estructurado

import streamlit as st
import pandas as pd
import numpy as np

st.set_page_config(page_title="Panel de ventas", page_icon="💰", layout="wide")

st.title("Panel de ventas 2026")
st.caption("Datos actualizados a 30 de marzo de 2026. Fuente: CRM interno.")

st.divider()

st.header("Resumen ejecutivo", divider="blue")
col1, col2, col3 = st.columns(3)
col1.metric("Ingresos Q1", "€ 124.500", "+15,3%")
col2.metric("Clientes activos", "842", "+67")
col3.metric("Ticket medio", "€ 148", "+€ 12")

st.header("Análisis detallado", divider="blue")

st.subheader("Evolución mensual")
df = pd.DataFrame({"mes": range(1, 4), "ventas": [38000, 41200, 45300]})
st.line_chart(df.set_index("mes"))

st.subheader("Top 5 productos")
st.text("SKU-001  |  Laptop Pro 14    |  €1.299  |  89 uds")
st.text("SKU-002  |  Monitor 27''     |  €349    |  134 uds")
st.text("SKU-003  |  Teclado mec.     |  €129    |  201 uds")

st.divider()
st.caption("Dashboard creado con Streamlit 1.40 y CertiDevs")

La estructura jerárquica clara no solo mejora la experiencia visual del usuario, sino que también facilita la navegación por teclado y la accesibilidad de la aplicación.

st.write: el comodín de salida

Aunque no es estrictamente un encabezado, st.write merece mención por su versatilidad. Es una función de propósito general que detecta automáticamente el tipo de dato que recibe y lo renderiza de la forma más apropiada:

import streamlit as st
import pandas as pd

st.write("Texto simple")
st.write("**Markdown** con _formato_")
st.write(42)
st.write({"clave": "valor", "lista": [1, 2, 3]})
st.write(pd.DataFrame({"A": [1, 2], "B": [3, 4]}))

st.write acepta cadenas, números, DataFrames, diccionarios, figuras de Matplotlib y Plotly, y cualquier objeto con representación __repr__. Es la forma más rápida de mostrar datos durante el desarrollo y prototipado, aunque para producción es preferible usar los componentes específicos (st.dataframe, st.metric, st.json) que ofrecen mayor control sobre la presentación.