Skip to content

Além do básico: guia completo dos botões no Streamlit

Olaf Källström
Name
Olaf Källström

Updated on

O Streamlit transforma scripts Python em apps interativos com pouquíssimo esforço, e os botões costumam ser a primeira interação esperada pelas pessoas usuárias. O widget st.button parece simples, mas libera fluxos que vão de alternâncias rápidas a operações complexas em várias etapas. Este guia atualizado resume a API moderna, corrige equívocos comuns e apresenta padrões comprovados para construir experiências confiáveis baseadas em botões.

Quer um componente de analytics visual pronto para usar nos seus projetos com Streamlit?

PyGWalker (opens in a new tab) incorpora uma interface de exploração semelhante ao Tableau diretamente no seu app Streamlit. Veja como explorar dados com o PyGWalker (opens in a new tab) ou leia o guia de integração.

Entendendo o st.button

Passo a passo rápido

Em essência, st.button renderiza um elemento clicável e retorna True durante a execução imediatamente após o clique. Esse valor booleano é suficiente para fluxos mais simples:

import streamlit as st
 
if st.button("Dizer olá"):
    st.write("Olá, Streamlit!")

O Streamlit reexecuta todo o script sempre que um widget muda. Por conta desse modelo reativo, garanta que o trabalho dentro do bloco if seja idempotente ou protegido por estado adicional.

Principais argumentos que você deve conhecer

st.button aceita vários argumentos opcionais que cobrem a maioria das necessidades de personalização:

  • key: identificador único quando há vários botões com o mesmo rótulo.
  • help: texto exibido como tooltip ao passar o cursor.
  • on_click: callback executado quando o botão é pressionado.
  • args / kwargs: argumentos posicionais e nomeados encaminhados ao callback.
  • type: escolha entre os estilos "primary" e "secondary" para seguir o tema do Streamlit.
  • disabled: impede a interação com o botão.
  • use_container_width: amplia o botão para ocupar toda a largura do contêiner pai.
def refresh_data(verbose: bool = False, limit: int | None = None) -> None:
    st.session_state["last_result"] = load_data(limit=limit)
    if verbose:
        st.success("Dados atualizados")
 
st.button(
    "Atualizar dados",
    key="refresh",
    help="Buscar os registros mais recentes na API",
    type="primary",
    use_container_width=True,
    on_click=refresh_data,
    args=(True,),
    kwargs={"limit": 500},
)

Lidando com interações além do retorno

Trabalhando com callbacks e estado de sessão

Os callbacks são executados depois que o Streamlit coleta as mudanças dos widgets, sendo ideais para encapsular lógica e atualizar o 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("Registrar horário", on_click=mark_timestamp, type="primary")
 
st.write("Último clique:", st.session_state.last_clicked or "Ainda não")

Callbacks mantêm o script principal declarativo, evitam if profundamente aninhados e preservam o estado entre reexecuções.

Criando comportamento de alternância

Botões não permanecem pressionados, mas você pode combiná-los com o estado de sessão para obter interações semelhantes a toggles:

import streamlit as st
 
st.session_state.setdefault("show_advanced", False)
 
if st.button("Mostrar/ocultar opções avançadas"):
    st.session_state.show_advanced = not st.session_state.show_advanced
 
if st.session_state.show_advanced:
    st.info("A configuração avançada aparece aqui.")

Para controles persistentes (por exemplo, ligar/desligar), considere widgets como st.checkbox ou st.toggle, que comunicam melhor o estado.

Técnicas de layout para botões

O Streamlit organiza os elementos na ordem em que aparecem, mas você ainda tem controle de layout por meio dos contêineres:

col1, col2 = st.columns(2)
with col1:
    st.button("Anterior", key="prev", type="secondary")
with col2:
    st.button("Próximo", key="next", type="primary", use_container_width=True)
 
with st.sidebar:
    st.button("Redefinir filtros", key="reset")

Use st.container() ou st.expander() para agrupar ações relacionadas e st.columns() para alinhar botões na mesma linha sem depender de HTML bruto.

Opções de estilo e sobrescritas com CSS

O Streamlit limita propositalmente a personalização direta para preservar consistência, mas você ainda tem alternativas:

  • Prefira o preset nativo type="primary" para dar destaque e use_container_width=True para layouts responsivos.
  • Ajuste as cores padrão por meio das configurações globais de tema (.streamlit/config.toml).
  • Quando precisar de um estilo sob medida, injete CSS delimitado com 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("Botão em degradê", key="custom")
    st.markdown("</div>", unsafe_allow_html=True)

Mantenha as sobrescritas de CSS enxutas; blocos inline grandes são difíceis de manter e podem quebrar se o Streamlit alterar nomes internos de classes.

Padrões práticos

  • Revelação progressiva: combine um botão com st.session_state para exibir campos ou textos adicionais apenas quando necessário.
  • Etapas de processamento de dados: desabilite botões (disabled=True) até que pré-requisitos, como upload de arquivos ou tokens de autenticação, estejam disponíveis.
  • Fluxos de download: use st.download_button quando precisar entregar arquivos; deixe st.button para lógica dentro do app.

Conclusão

Os botões sustentam muitos percursos de usuário no Streamlit. Ao combinar o retorno booleano, a API de callbacks e st.session_state, você coordena comportamentos complexos sem abandonar o paradigma reativo. Aproveite os primitivos de layout para alinhar componentes, recorra ao CSS apenas quando necessário e considere outros widgets quando for mais claro indicar um estado persistente. Botões bem planejados deixam seus apps Streamlit rápidos, intuitivos e confiáveis.

Perguntas frequentes

Como criar um botão no Streamlit?

Use st.button("Rótulo"). A função retorna True na execução disparada pelo clique, portanto coloque a lógica no bloco if correspondente ou forneça um callback via on_click.

Como posicionar um botão no Streamlit?

Envolva widgets com primitivos de layout como st.columns, st.container, st.sidebar ou st.expander. Esses contêineres controlam a posição sem precisar de HTML.

Como criar um botão de opção no Streamlit?

Utilize st.radio(label, options) para apresentar escolhas mutuamente exclusivas. A opção selecionada é retornada imediatamente e pode ser armazenada em st.session_state para a lógica subsequente.

Quais são as desvantagens do Streamlit?

O modelo de reexecução de scripts do Streamlit simplifica o desenvolvimento, mas pode ser limitante quando você precisa de controle detalhado de layout, tarefas demoradas em segundo plano ou personalização de estilo avançada. Mesmo assim, o ecossistema evolui rapidamente: novos widgets, opções de tema e utilitários de estado de sessão reduzem essas lacunas constantemente.