Tabla

Lista renderizada por el servidor. El <table> de la plantilla sigue siendo la fuente de la verdad y la celda es libre. El JavaScript entra solo donde el HTML no llega: ordenar por columna y marcar filas en bloque.

Ejemplos

Las variantes son clases en la propia tabla. Por defecto las filas se separan con un borde inferior, y no con cebra: en una lista de treinta filas la cebra se vuelve ruido. Quien quiera cebra, que la pida.

Cómo usar

Marca la <table> con data-tuc-table y se inicializa sola, incluida la que llegue después por HTMX. En cada columna ordenable, data-sort indica el tipo y data-field indica el nombre que va en la 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">Importe</th>
    <th data-sort="none" class="tuc-table__actions">Acciones</th>
  </tr></thead>
  <tbody>
    <tr data-id="12">
      <td>Constructora Valle</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>

En la plantilla de Django

El bucle es el de siempre. El data-id de la fila es lo que envía la selección múltiple, y el {% empty %} dibuja el estado vacío.

<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">Estado</th>
    <th data-sort="number" data-field="amount" class="is-number">Importe</th>
    <th data-sort="none" class="tuc-table__actions">Acciones</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">Ningún contrato encontrado.</td></tr>
    {% endfor %}
  </tbody>
</table>

En JavaScript

Para pasar onSort y onSelect, que no existen como atributo, o para leer la selección.

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

Ordenación

Ordenar es trabajo del servidor, y eso es lo predeterminado. En una lista paginada, reordenar las veinte filas que están en pantalla produce un orden falso: el mayor importe real puede estar en la página 7, y la tabla pasa a mentir con cara de verdad. Quien sabe ordenar el conjunto entero es la base de datos.

Por eso, en el modo servidor, el encabezado se convierte en un <a> a la misma URL con ?sort= y ?dir=. Funciona sin nada de JavaScript, funciona con el hx-boost de HTMX, se abre en otra pestaña y vuelve con el botón del navegador. La flecha sale de la query string, así que sigue siendo correcta después de recargar. El enlace conserva el resto de la query string — filtro y búsqueda no se pierden — y quita el page: seguir en la página 7 con otro orden mostraría un trozo del medio de una lista que nadie vio.

En la vista

?sort y ?dir entran en el order_by() antes del Paginator, que es exactamente donde tiene que ocurrir la ordenación. Traduce el nombre de la URL con una lista cerrada: pasar el parámetro directo a order_by() dejaría a cualquiera ordenar por cualquier campo, y un nombre inexistente tumba la vista con 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: sin un orden total, la misma fila puede aparecer en dos 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>

La paginación hace lo mismo desde el otro lado: el enlace de página conserva sort y dir, así que pasar de página no deshace el orden.

Tipos y valor crudo

El valor crudo importa en el modo cliente: 12/09/2026 no es una fecha que el navegador lea en el formato brasileño, y "hace 3 días" o "En revisión" no ordenan como texto. Escribe el valor mostrado para la persona y la fecha ISO o el número en data-sort-value.

En pantalla, para tabla pequeña

data-sort-mode="client" existe para el otro caso: tabla pequeña y completa, sin paginación, donde ordenar en pantalla es lo correcto. Ahí el encabezado se convierte en <button>, porque no hay adónde navegar, y el aria-sort se actualiza con cada clic.

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

Con HTMX

Como el encabezado y la paginación son enlaces de verdad, el hx-boost en un ancestro basta: HTMX cambia el contenido sin recargar, la URL acompaña y la tabla nueva se inicializa sola en el 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 la navegación por tu cuenta, pasa onSort: con él definido, el clic se cancela y quien lo escribió toma el control. El evento tucano:sort se dispara igualmente, antes de la navegación.

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

Selección múltiple

La selección sigue siendo un formulario. Con data-selectable, cada fila recibe un <input type="checkbox" name="selected"> de verdad con su data-id como valor — en Django llega como request.POST.getlist("selected"), sin JavaScript de por medio.

<form method="post" action="{% url 'contracts-approve' %}">
  {% csrf_token %}
  <table data-tuc-table data-selectable>...</table>
  <button class="tuc-btn is-primary">Aprobar seleccionados</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")

La casilla del encabezado marca y desmarca la página entera y muestra el estado mixto cuando solo una parte está marcada. Cada cambio dispara tucano:select en la tabla, con los valores marcados — los mismos que el formulario enviaría.

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

La celda es libre

Dentro del <td> cabe lo que quieras. Lo que ofrece la biblioteca son las disposiciones que aparecen en todo listado, para que nadie tenga que reinventar la alineación de un avatar junto a un nombre.

Teclado y accesibilidad

Todo lo que la tabla añade es elemento nativo: enlace, botón y casilla. Por eso cada uno ya está en el recorrido del Tab y responde a las teclas de siempre.

El encabezado ordenado anuncia aria-sort="ascending" o "descending"; los demás, "none". La casilla del encabezado se llama "Selecionar todas as linhas desta página" y la de cada fila, "Selecionar linha"; el estado mixto es el indeterminate nativo, que el lector de pantalla anuncia. La flecha de ordenación es aria-hidden: quien informa la dirección es el atributo, y no el dibujo.

API

Generada a partir del código en cada build — si algo no está aquí, no existe.

Opciones

Las notas de esta tabla salen de los comentarios del código fuente, que están escritos en portugués.