Referencia

Props y API

Todas las props son opcionales. En React y Vue van en camelCase; en HTML, como atributos en kebab-case.

Props y atributos

La columna «HTML» indica el atributo cuando cambia de nombre (sleepAfter → sleep-after).

Prop	HTML	Tipo	Por defecto	Descripción
`mood`	igual	`"dots" \| "hearts" \| "spiral" \| "sleepy" \| "cross" \| "angry" \| "surprised" \| "happy" \| "sad" \| "wink" \| "thinking"`	`"dots"`	Expresión base, a la que vuelve tras cada animación.
`color`	igual	`"hostarys" \| "lavanda" \| "noche" \| "negro" \| "ember" \| "cyan" \| "lime" \| "violet" \| string`	`"negro"`	Preset de marca o cualquier color CSS. En la web de Hostarys, usa "hostarys".
`eye`	igual	`string`	`"#f0ebe4"`	Color de los ojos.
`bg`	igual	`string`	`"transparent"`	Fondo del lienzo.
`glow`	igual	`boolean \| number`	`false`	Resplandor del color de la llama; un número ajusta la intensidad (p. ej. 1.5).
`accessory`	igual	`AccessoryName \| AccessoryName[]`	`—`	Uno o varios: glasses, sunglasses, bowtie, crown, santa, headphones, witch, pumpkin, scarf, party, flowers, heart, beach, viking, axe, astronaut, backpack, pirate, eyepatch, wizard, wand, chef, spoon, samurai, katana, cape, mask, deerstalker, magnifier, guitar, goggles, flask, knight, shield, cap, vinyl, star, robot, wrench, ghost, headset, gamepad, laptop, firefighter, extinguisher, surfboard, lei, antlers, rednose, horns, wings, explorer, binoculars, tophat, carrot, broom, beanie, skigoggles, skis, elfhat, elfears, candycane, magi, chest, earmuffs, skates, cocoa, sack, startrail. Dos de la misma zona (cabeza, cara, cuello, mano, orejas) chocan: gana el primero.
`season`	igual	`"auto" \| "halloween" \| "christmas" \| "newyear" \| "valentine" \| "spring" \| "summer"`	`—`	Accesorios de temporada. "auto" los elige por la fecha en España (calendario en el kit de marca). Los accesorios explícitos ganan si ocupan la misma zona.
`paused`	igual	`boolean`	`false`	Fotograma fijo y determinista, sin animación ni interacción: miniaturas, rejillas y capturas.
`status`	igual	`"online" \| "busy" \| "degraded" \| "down" \| "maintenance"`	`—`	Estado de servidor: fija la expresión base y evita que se duerma.
`sound`	igual	`boolean`	`false`	Sonidos sintetizados (necesitan un clic previo del usuario).
`sleepAfter`	`sleep-after`	`number`	`20`	Segundos sin actividad hasta dormirse. 0 = nunca.
`drag`	igual	`boolean`	`false`	Se puede arrastrar y lanzar. Vuelve con resetPosition().
`reactToPage`	`react`	`boolean`	`false`	Reacciona a la página: scroll rápido, formularios, copiar, conexión.
`social`	igual	`boolean`	`true`	Mira y reacciona a otros Marcianos de la página.
`lite`	igual	`boolean \| "auto"`	`false`	Modo ligero (menos efectos). "auto": solo en equipos modestos.
`hiddenStart`	`hidden-start`	`boolean`	`false`	Empieza apagado; aparece con enter().
`interactive`	igual	`boolean`	`true`	Ratón, toques, teclado (Intro / espacio = toque) y sueño automático. Interactivo, es un botón enfocable.
`label`	igual	`string`	`"Marciano"`	Nombre accesible para lectores de pantalla.
`decorative`	igual	`boolean`	`false`	Solo decoración: oculto a lectores de pantalla y sin foco. Úsalo en rejillas e ilustraciones.
`motion`	igual	`"reduce" \| "full"`	`—`	"reduce" fuerza el movimiento reducido; "full" ignora prefers-reduced-motion. Por defecto respeta la preferencia del sistema.
`size`	igual	`number \| string`	`240`	Solo React y Vue. Ancho (número = px). El alto se ajusta solo. En HTML, usa CSS (width).
`onMoodChange`	`moodchange (evento)`	`(detail, event) => void`	`—`	Cada cambio real de expresión. detail: { mood, previous, queue, running }.
`onQueueChange`	`queuechange (evento)`	`(detail, event) => void`	`—`	Cambio de la cola pendiente (o de si está reproduciendo). detail: { queue, running }.
`onReady, onPoke, onSleep, onWake…`	`ready, poke, sleep, wake… (eventos)`	`(detail, event) => void`	`—`	Un prop por evento: onReady, onPoke ({ count }), onSleep, onWake, onDragStart / onDragEnd ({ x, y }), onSayStart / onSayEnd ({ text }). Ver la tabla de eventos.
`className, style, …`	igual	`HTMLAttributes`	`—`	Cualquier atributo HTML (aria-, id, data-…) pasa al elemento.

Métodos y eventos

Disponibles en el elemento (ref.current en React). Los marcados con ✓ también están en los controles de useMarciano().

Nombre	Tipo	Devuelve	Descripción	Hook
`play(mood)`	método	`Promise<void>`	Interrumpe lo que hace y reproduce esa expresión ya.	✓
`queue(...moods)`	método	`Promise<void>`	Añade expresiones a la cola; se reproducen en orden.	✓
`clearQueue()`	método	`void`	Vacía la cola pendiente.	✓
`stop()`	método	`void`	Vacía la cola y vuelve ya a la expresión base.	✓
`say(text?, { ms })`	método	`Promise<void>`	Bocadillo con texto y boca animada. ms = duración (por defecto según la longitud). Sin texto muestra el contenido hijo del elemento.	✓
`enter()`	método	`Promise<void>`	Aparece encendiéndose desde chispas (ideal con hiddenStart).	✓
`exit()`	método	`Promise<void>`	Se apaga en una nube de humo.	✓
`lipSync(media)`	método	`void`	Mueve la boca siguiendo el volumen de un <audio> o <video>.	✓
`stopLipSync()`	método	`void`	Deja de seguir el audio.	✓
`resetPosition()`	método	`void`	Vuelve a su sitio tras arrastrarlo.	✓
`mood`	propiedad	`MoodName`	Expresión actual (solo lectura).	✓
`pending`	propiedad	`MoodName[]`	Cola de expresiones pendientes (solo lectura).	—
`ready`	evento	`CustomEvent`	Primer fotograma pintado.	—
`moodchange`	evento	`CustomEvent`	Cambio real de expresión. detail: { mood, previous, queue, running }.	—
`queuechange`	evento	`CustomEvent`	Cambio de la cola. detail: { queue, running }.	—
`poke`	evento	`CustomEvent`	Le han tocado (clic, toque o teclado). detail: { count } (3 = mareo, 6 = KO).	—
`sleep / wake`	evento	`CustomEvent`	Se duerme por inactividad / se despierta.	—
`dragstart / dragend`	evento	`CustomEvent`	Arrastre con drag. detail: { x, y } (y cancelled en dragend).	—
`saystart / sayend`	evento	`CustomEvent`	Empieza y acaba un bocadillo. detail: { text }.	—

Ref y eventos

"use client";
import { useRef } from "react";
import { Marciano, type MarcianoFlameElement } from "@hostarys/marciano";

export function ConEventos() {
  const ref = useRef<MarcianoFlameElement>(null);
  return (
    <Marciano
      ref={ref}                                  // el ref es el propio elemento
      onMoodChange={({ mood, previous }) => console.log(previous, "→", mood)}
      onQueueChange={({ queue }) => console.log("cola:", queue)}
      onClick={() => console.log(ref.current?.pending)}
    />
  );
}

// Sin React: el mismo evento en el DOM
document.querySelector("marciano-flame")
  .addEventListener("moodchange", e => console.log(e.detail.mood));

En vivo

Pulsa un botón para ver los eventos moodchange y queuechange