Tabela

Lista renderizada pelo servidor. O <table> do template continua sendo a fonte da verdade e a célula é livre. O JavaScript entra só onde o HTML não alcança: ordenar pela coluna e marcar linhas em massa.

Exemplos

As variantes são classes na própria tabela. Por padrão as linhas se separam por uma borda de baixo, e não por zebra: numa lista de trinta linhas a zebra vira ruído. Quem quiser zebra pede.

Como usar

Marque a <table> com data-tuc-table e ela inicializa sozinha, inclusive a que chegar depois por HTMX. Em cada coluna ordenável, data-sort diz o tipo e data-field diz o nome que vai na URL.

<table data-tuc-table data-selectable>
  <thead><tr>
    <th data-sort="text" data-field="customer" style="width:38%">Cliente</th>
    <th data-sort="number" data-field="amount" class="is-number">Valor</th>
    <th data-sort="none" class="tuc-table__actions">Ações</th>
  </tr></thead>
  <tbody>
    <tr data-id="12">
      <td>Construtora Vale</td>
      <td class="is-number" data-sort-value="12400">R$ 12.400,00</td>
      <td class="tuc-table__actions">
        <button type="button" class="tuc-btn is-outline is-icon is-sm" aria-label="Editar">...</button>
      </td>
    </tr>
  </tbody>
</table>

No template do Django

O laço é o de sempre. O data-id da linha é o que a seleção em massa posta, e o {% empty %} desenha o estado vazio.

<table data-tuc-table data-selectable>
  <thead><tr>
    <th data-sort="text" data-field="customer" style="width:38%">Cliente</th>
    <th data-sort="text" data-field="status">Situação</th>
    <th data-sort="number" data-field="amount" class="is-number">Valor</th>
    <th data-sort="none" class="tuc-table__actions">Ações</th>
  </tr></thead>
  <tbody>
    {% for obj in page_obj %}
    <tr data-id="{{ obj.pk }}">
      <td>
        <span class="tuc-table__user">
          <span class="tuc-table__avatar"><img src="{{ obj.photo.url }}" alt=""></span>
          <span>{{ obj.name }}<span class="tuc-table__sub">{{ obj.email }}</span></span>
        </span>
      </td>
      <td><span class="tuc-badge is-success">{{ obj.get_status_display }}</span></td>
      <td class="is-number" data-sort-value="{{ obj.amount }}" data-tuc-format="brl">{{ obj.amount }}</td>
      <td class="tuc-table__actions">
        <a class="tuc-btn is-outline is-icon is-sm" href="{% url 'contract-edit' obj.pk %}" aria-label="Editar">...</a>
      </td>
    </tr>
    {% empty %}
    <tr><td colspan="5" class="tuc-table__empty">Nenhum contrato encontrado.</td></tr>
    {% endfor %}
  </tbody>
</table>

Em JavaScript

Para passar onSort e onSelect, que não existem como atributo, ou para ler a seleção.

const t = new Tucano.Table('#contracts', { selectable: true, sortMode: 'client' });
t.getSelected();          // ['12', '15'] — os data-id marcados
t.clearSelection();
t.sort(2, 'desc', 'number');
t.destroy();              // solta os listeners

Ordenação

Ordenar é trabalho do servidor, e esse é o padrão. Numa lista paginada, reordenar as vinte linhas que estão na tela produz uma ordem falsa: o maior valor real pode estar na página 7, e a tabela passa a mentir com cara de verdade. Quem sabe ordenar o conjunto inteiro é o banco.

Por isso, no modo servidor, o cabeçalho vira um <a> para a mesma URL com ?sort= e ?dir=. Funciona sem JavaScript nenhum, funciona com o hx-boost do HTMX, abre em outra aba e volta pelo botão do navegador. A seta sai da query string, então continua certa depois do recarregamento. O link preserva o resto da query string — filtro e busca não se perdem — e tira o page: continuar na página 7 com outra ordem mostraria um pedaço do meio de uma lista que ninguém viu.

Na view

?sort e ?dir entram no order_by() antes do Paginator, que é exatamente onde a ordenação tem de acontecer. Traduza o nome da URL por uma lista fechada: passar o parâmetro direto ao order_by() deixaria qualquer um ordenar por qualquer campo, e um nome inexistente derruba a view com FieldError.

from django.core.paginator import Paginator

ORDERS = {"customer": "name", "status": "status", "amount": "amount"}

def contracts(request):
    field = ORDERS.get(request.GET.get("sort"), "name")
    if request.GET.get("dir") == "desc":
        field = f"-{field}"
    # "pk" desempata: sem ordem total, a mesma linha pode aparecer em duas páginas.
    qs = Contract.objects.order_by(field, "pk")
    page_obj = Paginator(qs, 20).get_page(request.GET.get("page"))
    return render(request, "contracts/list.html", {"page_obj": page_obj})

<table data-tuc-table>...</table>
<div data-tuc-pagination
     data-page="{{ page_obj.number }}"
     data-pages="{{ page_obj.paginator.num_pages }}"></div>

A paginação faz a mesma coisa pelo outro lado: o link de página preserva sort e dir, então virar a página não desfaz a ordem.

Tipos e valor cru

O valor cru importa no modo cliente: 12/09/2026 não é uma data que o navegador leia no formato brasileiro, e "há 3 dias" ou "Em análise" não ordenam como texto. Escreva o valor exibido para a pessoa e o ISO ou o número em data-sort-value.

Na tela, para tabela pequena

data-sort-mode="client" existe para o outro caso: tabela pequena e completa, sem paginação, onde ordenar na tela é a coisa certa. Ali o cabeçalho vira <button>, porque não há para onde navegar, e o aria-sort é atualizado a cada clique.

<table data-tuc-table data-sort-mode="client">...</table>

Com HTMX

Como o cabeçalho e a paginação são links de verdade, o hx-boost num ancestral basta: o HTMX troca o conteúdo sem recarregar, a URL acompanha e a tabela nova se inicializa sozinha no htmx:afterSwap.

<div hx-boost="true">
  <table data-tuc-table>...</table>
  <div data-tuc-pagination data-page="3" data-pages="12"></div>
</div>

Para decidir a navegação por conta própria, passe onSort: com ele definido, o clique é cancelado e quem escreveu assume. O evento tucano:sort sai de qualquer jeito, antes da navegação.

new Tucano.Table('#contracts', {
  onSort: ({ column, field, direction }, table) => {
    htmx.ajax('GET', `?sort=${field}&dir=${direction}`, '#list');
  },
});

Seleção em massa

A seleção continua sendo um formulário. Com data-selectable, cada linha ganha um <input type="checkbox" name="selected"> de verdade com o data-id dela como valor — no Django chega como request.POST.getlist("selected"), sem JavaScript no meio.

<form method="post" action="{% url 'contracts-approve' %}">
  {% csrf_token %}
  <table data-tuc-table data-selectable>...</table>
  <button class="tuc-btn is-primary">Aprovar selecionados</button>
</form>

from django.views.decorators.http import require_POST

@require_POST
def approve(request):
    ids = request.POST.getlist("selected")
    Contract.objects.filter(pk__in=ids).update(status="approved")
    return redirect("contracts")

A caixa do cabeçalho marca e desmarca a página inteira e mostra o estado misto quando só parte está marcada. Cada mudança dispara tucano:select na tabela, com os valores marcados — os mesmos que o formulário enviaria.

document.querySelector('#contracts').addEventListener('tucano:select', (e) => {
  e.detail.selected;   // ['1', '3']
  e.detail.row;        // a <tr> que mudou
});

A célula é livre

Dentro do <td> cabe o que você quiser. O que a biblioteca oferece são os arranjos que aparecem em toda listagem, para ninguém ter de reinventar o alinhamento de um avatar ao lado de um nome.

Teclado e acessibilidade

Tudo o que a tabela acrescenta é elemento nativo: link, botão e caixa de seleção. Por isso cada um já está no caminho do Tab e responde às teclas de sempre.

O cabeçalho ordenado anuncia aria-sort="ascending" ou "descending"; os outros, "none". A caixa do cabeçalho se chama "Selecionar todas as linhas desta página" e cada linha, "Selecionar linha"; o estado misto é o indeterminate nativo, que o leitor de tela anuncia. A seta de ordenação é aria-hidden: quem informa o sentido é o atributo, e não o desenho.

API

Gerada do código a cada build — se algo não está aqui, não existe.

Opções