# Insignia

> Una pastilla pequeña para estados, versiones y contadores. Un componente nativo de Pyzed para GUIs de escritorio en Python, con vista previa, ejemplos y su API.

Source: https://albakore.github.io/pyzed/es/library/badge/

:::tip[En pocas palabras]
Una pastilla de color diminuta con una o dos palabras, como “beta” o “3 errores”.
:::

Una pastilla pequeña con texto y un icono opcional. `tint` elige un color semántico y `variant` es `"soft"` (por defecto), `"solid"` o `"outline"`.

`ui.badge` · Categoría: [Visualización](https://albakore.github.io/pyzed/es/library/#visualización) · [Referencia completa →](https://albakore.github.io/pyzed/es/reference/ui/#badge)

**Código:**

```python
pz.row([
    ui.badge("accent"),
    ui.badge("success", tint="success"),
    ui.badge("warning", tint="warning"),
    ui.badge("error", tint="error", icon="circle-x"),
], spacing=8)
```

## Cuándo usarlo

- Para estados cortos de solo lectura: `beta`, `M` (modificado), `v0.4`, `3 errores`.
- Para un número redondo encima de un icono usa [Contador](https://albakore.github.io/pyzed/es/library/count-badge/).

## Uso

```python
import pyzed as pz
from pyzed import ui

pz.row([
    ui.badge("accent"),
    ui.badge("success", tint="success"),
    ui.badge("warning", tint="warning"),
    ui.badge("error", tint="error", icon="circle-x"),
], spacing=8)
```

## Variantes

:::note[Sobre estas capturas]
Cada captura la graba pyzed mismo, fuera de pantalla a 2x, en One Dark o One Light según el tema de este sitio, y recortada al componente para que se vea a su tamaño real. El puntero pasa por encima, pulsa o escribe en él; un componente que no reacciona al puntero recorre algunos temas. Con movimiento reducido ves el primer fotograma. Abre **Código** bajo una captura para ver el fragmento que la dibuja; los nombres libres como `on_save` son tus propios callbacks.
:::

### Tinte

```python
ui.badge("accent")
```

```python
ui.badge("passed", tint="success")
```

```python
ui.badge("pending", tint="warning")
```

```python
ui.badge("failed", tint="error")
```

```python
ui.badge("info", tint="info")
```

```python
ui.badge("custom", tint="#c678dd")
```

### Variante

```python
ui.badge("soft")
```

```python
ui.badge("solid", variant="solid")
```

```python
ui.badge("outline", variant="outline")
```

### Con icono

```python
ui.badge("new", icon="sparkles")
```

```python
ui.badge("3 errors", tint="error", icon="circle-x")
```

```python
ui.badge("verified", tint="success", variant="solid", icon="check")
```

### Estados y eventos

```python
ui.badge("beta", size="sm")
```

```python
ui.badge("Pro", size="lg", icon="star")
```

```python
ui.badge("3 issues", tint="warning", on_press=on_press)
```

## Eventos

Insignia tiene **1 evento propios**, en la tabla de abajo. Como todo widget, también tiene los **18 eventos comunes** (`click`, `double_click`, `right_click`, `mouse_enter`, `drag`, `key_down`, `resize`…), que se conectan con `.on(...)`: mira [Eventos](https://albakore.github.io/pyzed/es/guides/events/) y [Eventos de cada componente](https://albakore.github.io/pyzed/es/library/events/).

| Evento | El handler recibe | Cuándo |
| --- | --- | --- |
| `on_press` | `()` | La hace pulsable. |

**El handler recibe** es lo que Pyzed le pasa a tu función: `()` es nada. Cualquier handler también puede ser un mensaje (un valor que no se puede llamar), que va a `update()`.

### Manejar los eventos

Los mismos eventos escritos de tres formas. **Imperativa**: métodos de la app que cambian `self`. **Declarativa**: los handlers producen mensajes y un único `update()` decide. **Funcional**: una función pura dibuja un estado inmutable y pide cambios con `set_state(...)`. Mira [Imperativo, declarativo y funcional](https://albakore.github.io/pyzed/es/guides/code-styles/).

**Imperativo:**

```python
class Inbox(pz.App):
    def __init__(self):
        self.unread = 3

    def view(self):
        return ui.badge(f"{self.unread} new", tint="accent",
                        on_press=lambda: setattr(self, "unread", 0))   # on_press makes it clickable
```

**Declarativo:**

```python
class Inbox(pz.App):
    unread = 3

    def update(self, message):
        if message == "read all":
            self.unread = 0

    def view(self):
        return ui.badge(f"{self.unread} new", on_press="read all")
```

**Funcional:**

```python
from dataclasses import dataclass

@dataclass(frozen=True)
class State:
    unread: int = 3

def view(state, set_state):
    return ui.badge(f"{state.unread} new", on_press=lambda: set_state(unread=0))
```

## Propiedades y API

### `ui.badge`

```python
badge(
    content,
    *,
    tint='accent',
    variant='soft',
    icon=None,
    size='md',
    on_press=None,
    theme=None,
)
```

Una píldora pequeña para estados y contadores.

| Propiedad | Por defecto | Descripción |
| --- | --- | --- |
| `content` | *obligatorio* | Contenido: un `Widget`, un texto o un número (se convierte en texto). |
| `tint` | `"accent"` | Color semántico: `"accent"`, `"error"`, `"warning"`, `"success"`, `"info"` o un token. |
| `variant` | `"soft"` | `"soft"`, `"solid"` o `"outline"`. |
| `icon` | `None` | Nombre de un icono de Lucide (`pyzed icons` los lista). |
| `size` | `"md"` | `"sm"`, `"md"` o `"lg"`. |
| `theme` | `None` | Tema a usar en lugar del actual (`pyzed.theme.current()`). |

Eventos: `on_press` ([eventos](#eventos)).

[Referencia completa →](https://albakore.github.io/pyzed/es/reference/ui/#badge)

## Relacionados

- [Contador](https://albakore.github.io/pyzed/es/library/count-badge/): Un contador redondo que muestra 99+ por encima del máximo.
- [Indicador](https://albakore.github.io/pyzed/es/library/indicator/): Un punto de color para estado, presencia o cambios sin guardar.
- [Chip](https://albakore.github.io/pyzed/es/library/chip/): Una etiqueta compacta: pulsable como filtro y con ✕ para quitarla.