# Botón de icono

> Un botón cuadrado con solo un icono y un tooltip opcional. 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/icon-button/

:::tip[En pocas palabras]
Un botón pequeño con solo un dibujo (una lupa, un engranaje) en lugar de palabras.
:::

Un botón cuadrado y compacto que muestra un icono de [Lucide](https://lucide.dev). Es transparente por defecto, así que encaja en barras de herramientas, cabeceras de panel y barras de pestañas. `tooltip=` añade un tooltip al pasar el ratón.

`ui.icon_button` · Categoría: [Acciones](https://albakore.github.io/pyzed/es/library/#acciones) · [Referencia completa →](https://albakore.github.io/pyzed/es/reference/ui/#icon_button)

**Código:**

```python
pz.row([
    ui.icon_button("search", on_search, tooltip="Search"),
    ui.icon_button("settings", on_settings, tooltip="Settings"),
    ui.icon_button("bell", on_notifications, selected=True),
    ui.icon_button("plus", on_new, variant="filled"),
], spacing=6)
```

## Cuándo usarlo

- Para acciones frecuentes con un icono evidente (buscar, ajustes, cerrar, añadir).
- Dale siempre un `tooltip` cuando el icono solo pueda ser ambiguo.
- `selected=True` muestra un estado activo (un panel abierto, un filtro activado).

## Uso

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

pz.row([
    ui.icon_button("search", on_search, tooltip="Search"),
    ui.icon_button("settings", on_settings, tooltip="Settings"),
    ui.icon_button("bell", on_notifications, selected=True),
    ui.icon_button("plus", on_new, variant="filled"),
], spacing=6)
```

## 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.
:::

### Tamaño

```python
ui.icon_button("star", on_press, size="xs")
```

```python
ui.icon_button("star", on_press, size="sm")
```

```python
ui.icon_button("star", on_press, size="md")
```

```python
ui.icon_button("star", on_press, size="lg")
```

### Variante

```python
ui.icon_button("settings", on_press)
```

```python
ui.icon_button("settings", on_press, variant="filled")
```

```python
ui.icon_button("settings", on_press, variant="outline")
```

```python
ui.icon_button("settings", on_press, variant="solid")
```

```python
ui.icon_button("settings", on_press, variant="tinted")
```

### Color

```python
ui.icon_button("sparkles", on_press, color="accent")
```

```python
ui.icon_button("circle-check", on_press, color="success")
```

```python
ui.icon_button("triangle-alert", on_press, color="warning")
```

```python
ui.icon_button("trash-2", on_press, color="error", variant="outline")
```

### Estado

Dibujado tal como lo muestra el puntero: los tooltips solo se abren al pasar el ratón.

```python
ui.icon_button("panel-left", on_press, selected=True)
```

```python
ui.icon_button("lock", on_press, disabled=True)
```

```python
ui.icon_button("search", on_press, tooltip="Search")
```

### Estados y eventos

```python
ui.icon_button("bell", on_press, indicator="accent")
```

```python
ui.icon_button("trash-2", on_press, tint="error")
```

```python
ui.icon_button("refresh-cw", on_press, loading=True)
```

```python
ui.icon_button("search", on_press, tooltip="Search", keys="ctrl-f")
```

## Eventos

Botón de icono 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` | `()` | Mensaje o callable que se envía al pulsar. `None` deshabilita el control. |

**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 Toolbar(pz.App):
    def __init__(self):
        self.bold = False

    def toggle_bold(self):
        self.bold = not self.bold

    def view(self):
        return pz.row([
            ui.icon_button("bold", self.toggle_bold, selected=self.bold, tooltip="Bold", keys="ctrl-b"),
            ui.icon_button("trash-2", self.clear, tooltip="Clear", disabled=not self.bold),
        ], spacing=4)

    def clear(self):
        self.bold = False
```

**Declarativo:**

```python
from dataclasses import dataclass

@dataclass
class ToggleBold:
    pass

class Toolbar(pz.App):
    bold = False

    def update(self, message):
        if isinstance(message, ToggleBold):
            self.bold = not self.bold

    def view(self):
        return ui.icon_button("bold", ToggleBold(), selected=self.bold, tooltip="Bold")
```

**Funcional:**

```python
from dataclasses import dataclass

@dataclass(frozen=True)
class State:
    bold: bool = False

def view(state, set_state):
    return ui.icon_button("bold", lambda: set_state(bold=not state.bold),
                          selected=state.bold, tooltip="Bold")
```

## Consejos

:::tip
Ejecuta `pyzed icons` para buscar los nombres de iconos.
:::

## Propiedades y API

### `ui.icon_button`

```python
icon_button(
    name,
    on_press=None,
    *,
    size='md',
    variant='ghost',
    color=None,
    selected=False,
    disabled=False,
    tooltip=None,
    keys=None,
    tint=None,
    loading=False,
    indicator=None,
    theme=None,
)
```

Un botón cuadrado con solo un icono.

| Propiedad | Por defecto | Descripción |
| --- | --- | --- |
| `name` | *obligatorio* | Nombre del icono. |
| `size` | `"md"` | `"xs"`, `"sm"`, `"md"` o `"lg"`. |
| `variant` | `"ghost"` | Como en `ui.button`. Por defecto `"ghost"`. |
| `color` | `None` | Color del icono. |
| `selected` | `False` | Lo marca como seleccionado. |
| `disabled` | `False` | Lo deshabilita (ignora los clics). |
| `tooltip` | `None` | Texto del tooltip. |
| `keys` | `None` | Atajo que se muestra en el tooltip. |
| `tint` | `None` | Lo colorea (`"error"`, `"accent"`…). |
| `loading` | `False` | Cambia el icono por un spinner e ignora las pulsaciones. |
| `indicator` | `None` | Añade un punto de este color arriba a la derecha (sin leer, cambios…). |
| `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/#icon_button)

## Relacionados

- [Botón](https://albakore.github.io/pyzed/es/library/button/): El botón con tema: variantes, tamaños, iconos y atajos.
- [Tooltip](https://albakore.github.io/pyzed/es/library/tooltip/): Una pista que aparece al pasar el ratón, con su atajo opcional.
- [Barra de herramientas](https://albakore.github.io/pyzed/es/library/toolbar/): La barra bajo las pestañas: migas de pan y acciones.