> ## Documentation Index
> Fetch the complete documentation index at: https://docs.landerlab.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Controla los popups con la API de popups
> Abre, cierra y alterna popups de LanderLab desde botones, enlaces y código personalizado. Referencia completa de la API de JavaScript y de los enlaces sin código para abrir y cerrar.
La API de popups te permite controlar cualquier popup con código, en lugar de depender solo de los disparadores integrados (carga de página, retardo, desplazamiento, intención de salida). Llama a `window.llPopupsApi` desde un elemento Custom Code o desde cualquier script para abrir un popup con un botón, cerrarlo tras el envío de un formulario o integrarlo en tus propios sistemas.
**Usa el ID del popup, no su nombre.** Todo en la API apunta a un popup por su `id`. El **nombre** del popup (la etiqueta legible que ves en el editor) es solo un metadato para la analítica y la visualización: nunca se usa para apuntar a un popup. Si usas el nombre, no ocurrirá nada.
***
## Paso 1: prepara el popup
Antes de controlar un popup con código, configúralo para que no interfiera con tus disparadores y consigue un ID al que puedas referirte.
En la pestaña **Popup** de la barra lateral derecha, pon el **Trigger** en **Manual** (solo con botón). El popup no se abrirá nunca solo: solo aparecerá cuando lo abra tu enlace o tu script.
No *tienes* que usar Manual. La API funciona en cualquier popup, sea cual sea su disparador. Manual solo garantiza que el popup permanezca cerrado hasta que tú lo abras.
Cada popup tiene ya un ID único. Para encontrarlo, abre el panel **Popups** de la barra lateral izquierda, haz clic en los **tres puntos (acciones)** junto a tu popup y elige **Copy ID**. Pega ese valor allá donde la API te pida el ID del popup.
***
## La API de JavaScript (`window.llPopupsApi`)
Llama al objeto global `window.llPopupsApi` para abrir, cerrar o alternar un popup: con un evento personalizado, tras un retardo que tú controles o desde otro script. Pega el código en un elemento **Custom Code** de tu página.
```javascript theme={null}
// Abrir un popup concreto
window.llPopupsApi.open('promo-popup-id');
```
### El ID es opcional
Cada método acepta un ID de popup **opcional**:
* **Si pasas un ID** → la acción afecta solo a ese popup.
* **Si omites el ID** → la acción afecta a **todos los popups** de la página.
```javascript theme={null}
window.llPopupsApi.close('promo-popup-id'); // cerrar un popup
window.llPopupsApi.close(); // cerrar todos los popups de la página
```
### Métodos
| Método | Qué hace |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `open(id?)` | Fuerza la apertura del popup. Lo vuelve a abrir aunque el visitante lo hubiera cerrado antes en la misma sesión (tu llamada explícita tiene prioridad). |
| `close(id?)` | Cierra el popup con su animación. **No** guarda la cookie de “stay dismissed”: el popup puede volver a activarse. |
| `dismiss(id?)` | Cierra el popup **y** lo bloquea: guarda la cookie de 30 días si **Stay Dismissed** está activado, o la marca de sesión si lo está **Show Once**. Es lo que hace el botón de cierre integrado. |
| `toggle(id?)` | Abre el popup si está cerrado y lo cierra si está abierto. (Al abrirlo con toggle, se fuerza la apertura, igual que con `open`.) |
| `get(id?)` | Devuelve el elemento HTML del popup si pasas un ID (o `null` si no lo encuentra), o un array con todos los elementos de popup si omites el ID. |
**`close` frente a `dismiss`.** `close()` es un cierre temporal: los disparadores automáticos, como la intención de salida, pueden volver a activarse. `dismiss()` es permanente durante la sesión (y hasta 30 días con **Stay Dismissed**). Usa `close()` para un “quizás más tarde” y `dismiss()` para un “no volver a mostrar”.
### Ejemplos
```javascript Abrir desde un botón theme={null}
// Espera a que la página esté lista antes de enlazar nada.
// DOMContentLoaded garantiza que existan tanto tu botón como llPopupsApi.
document.addEventListener('DOMContentLoaded', function () {
const button = document.getElementById('my-button');
button.addEventListener('click', function () {
window.llPopupsApi.open('promo-popup-id');
});
});
```
```javascript Cerrar tras un retardo theme={null}
// Cierra automáticamente el popup 5 segundos después de abrirse
window.llPopupsApi.open('promo-popup-id');
setTimeout(function () {
window.llPopupsApi.close('promo-popup-id');
}, 5000);
```
```javascript Alternar / cerrar todos theme={null}
// Alternar un solo popup
window.llPopupsApi.toggle('promo-popup-id');
// Cerrar de una vez todos los popups de la página
window.llPopupsApi.close();
```
```javascript Obtener el elemento de un popup theme={null}
// Pasa un ID para obtener un elemento (o null si no lo encuentra)
const popup = window.llPopupsApi.get('promo-popup-id');
// Omite el ID para obtener un array con todos los popups de la página
const allPopups = window.llPopupsApi.get();
```
***
## Conviene saber
* **Ejecuta tu código cuando la página esté lista.** `window.llPopupsApi` solo existe una vez cargado el script de popups. Envuelve tus llamadas en un listener de `DOMContentLoaded`, como en el ejemplo **Abrir desde un botón**, para que la API esté disponible cuando la llames.
* **Modo de vista previa.** En las URLs de vista previa, la cookie de “Stay Dismissed” y la marca de “Show Once” nunca se leen ni se guardan, así que el popup siempre aparece mientras haces pruebas.
* **ESC para cerrar.** Si **Close on ESC** está activado en el popup, pulsar Esc cierra el popup que esté encima, sin necesidad de código.
* **`open` tiene prioridad sobre el cierre.** Llamar a `open()` vuelve a abrir un popup aunque el visitante lo hubiera cerrado, pero los disparadores automáticos del propio popup siguen respetando ese cierre. Usa `dismiss()` si quieres volver a bloquearlo.