Crea un widget flotante de feedback para tu app React

Renderiza un botón fijo que abre un panel basado en la Popover API del navegador, para que quede por encima de todas las capas de tu app sin pelearte con el z-index y se cierre con Escape. Al enviar, añade a los datos del formulario la ruta actual, la versión de la app, el id de la cuenta y el viewport, y envíalo desde el navegador con el SDK de Ikiform. Envía el email del usuario solo cuando marque una casilla pidiendo respuesta.

Qué cambia en un widget dentro de la app

Un formulario en una página espera a que la gente llegue hasta él. Un widget está en todas las pantallas, y eso cambia lo que puede salir mal. Tiene que quedar por encima de tus propios modales, menús y toasts. No debe perder un mensaje a medio escribir cuando alguien hace clic fuera. Y como la gente ha iniciado sesión, ya sabes quién es y dónde está, así que el widget debería enviarlo en lugar de preguntarlo.

Campos para una app

El componente

Necesita @ikiform/sdk y React 19, que tipa popover, popoverTarget y el evento toggle. El popoverTarget del botón lo vincula al panel, así que el navegador se encarga de abrirlo, de Escape y de devolver el foco al botón.

import { submit } from "@ikiform/sdk";
import { type FormEvent, type ToggleEvent, useId, useRef, useState } from "react";
import "./feedback-widget.css";

const FORM_ID = "frm_xxxxxxxxxxxxxxxx";
const FACES = ["Awful", "Bad", "Okay", "Good", "Great"];

interface Props {
  accountId: string;
  email: string;
  appVersion: string;
}

export function FeedbackWidget({ accountId, email, appVersion }: Props) {
  const panelId = useId();
  const attempt = useRef("");
  const [status, setStatus] = useState<"idle" | "sending" | "sent">("idle");
  const [error, setError] = useState("");

  function onToggle(event: ToggleEvent<HTMLDivElement>) {
    if (event.newState !== "open") return;
    attempt.current = crypto.randomUUID();
    if (status === "sent") setStatus("idle");
  }

  async function onSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    const data = new FormData(event.currentTarget);
    if (data.get("may_reply") === "true") data.set("email", email);
    data.set("route", window.location.pathname);
    data.set("app_version", appVersion);
    data.set("account_id", accountId);
    data.set("viewport", `${window.innerWidth}x${window.innerHeight}`);
    setStatus("sending");
    setError("");
    const result = await submit(FORM_ID, data, { idempotencyKey: attempt.current });
    if (result.ok) {
      setStatus("sent");
      return;
    }
    setError(result.error.fields?.rating?.[0] ?? result.error.message);
    setStatus("idle");
  }

  return (
    <>
      <button type="button" className="feedback-trigger" popoverTarget={panelId}>
        Feedback
      </button>
      <div id={panelId} popover="auto" className="feedback-panel" onToggle={onToggle} aria-label="Send feedback">
        {status === "sent" ? (
          <p role="status">Thanks, that helps.</p>
        ) : (
          <form onSubmit={onSubmit}>
            <fieldset>
              <legend>How is it going?</legend>
              {FACES.map((face, index) => (
                <label key={face}>
                  <input type="radio" name="rating" value={index + 1} required /> {face}
                </label>
              ))}
            </fieldset>
            <label htmlFor={`${panelId}-message`}>Tell us more</label>
            <textarea id={`${panelId}-message`} name="message" rows={4} maxLength={4000} />
            <label>
              <input type="checkbox" name="may_reply" value="true" /> The team can reply to me by email
            </label>
            <input name="_gotcha" type="text" tabIndex={-1} autoComplete="off" hidden />
            {error ? <p role="alert">{error}</p> : null}
            <button disabled={status === "sending"}>{status === "sending" ? "Sending" : "Send"}</button>
          </form>
        )}
      </div>
    </>
  );
}

• popover="auto" pone el panel en la top layer cuando está abierto. Se muestra por encima de tus diálogos y menús sin z-index, y se cierra cuando el usuario hace clic en otro sitio.
• Los hijos del panel siguen montados cuando se oculta, así que un borrador sobrevive a un clic fuera accidental. Tras un envío correcto, la línea de agradecimiento sustituye al formulario, lo que lo vacía, y la siguiente apertura muestra un formulario vacío.
• onToggle crea una clave nueva cada vez que se abre el panel. submit() la envía como cabecera Idempotency-Key, así que un doble clic guarda una sola respuesta. Consulta idempotencia.
• El email solo se rellena cuando la casilla está marcada. Sin marcar, la respuesta lleva el id de la cuenta pero ninguna dirección.

Los estilos por defecto del popover lo centran en la pantalla. Estas reglas lo fijan encima del botón:

.feedback-trigger {
  position: fixed;
  right: 16px;
  bottom: 16px;
}

.feedback-panel {
  inset: auto 16px 64px auto;
  margin: 0;
  width: min(360px, calc(100vw - 32px));
  max-height: calc(100dvh - 96px);
  overflow: auto;
}

Móntalo una vez

Renderiza el widget en el layout que envuelve las pantallas con sesión iniciada, para que aparezca en todas partes y sobreviva a la navegación. En el App Router de Next.js, el layout es un server component que lee la sesión y pasa props simples al widget de cliente:

import type { ReactNode } from "react";
import { FeedbackWidget } from "@/components/feedback-widget";
import { getSession } from "@/lib/session";

export default async function AppLayout({ children }: { children: ReactNode }) {
  const session = await getSession();
  return (
    <>
      {children}
      {session ? (
        <FeedbackWidget
          accountId={session.accountId}
          email={session.email}
          appVersion={process.env.NEXT_PUBLIC_APP_VERSION ?? "dev"}
        />
      ) : null}
    </>
  );
}

Marca el archivo del widget con "use client" en el App Router. En una app con Vite o React Router, renderízalo junto al outlet del router. Funciona igual.

Lo que el navegador puede y no puede probar

Este widget envía directamente desde el navegador con el id público del formulario. Para el feedback es el equilibrio correcto: no hay ruta de servidor que mantener, y el meta.user_agent de Ikiform es el navegador real del usuario. También significa que cualquiera puede enviar el account_id que quiera. Úsalo para consultar cosas, nunca para conceder nada.

Comprueba que funciona

1. En Allowed domains del formulario, añade el dominio de tu sitio, y localhost mientras desarrollas. Déjalo vacío para aceptar envíos desde cualquier lugar.
2. Abre el panel, escribe una nota, haz clic fuera y vuelve a abrirlo. La nota sigue ahí.
3. Abre un modal en tu app y luego el widget. El panel aparece por encima del modal.
4. Pulsa Escape. El panel se cierra y el foco vuelve al botón de feedback.
5. Elige una cara y haz doble clic en Enviar. Submissions muestra una sola respuesta, con route, app_version y account_id rellenos.
6. Envía una vez con la casilla de respuesta marcada. El Responder del email de notificación va al usuario.

Errores comunes

• Mantén el botón separado de tus propios elementos flotantes, como una burbuja de chat o un banner de cookies. Mueve uno de ellos, o abre el widget desde un elemento de menú.
• No muestres el botón en cada pantalla de un checkout o un editor donde la gente está concentrada. Ocúltalo ahí con una prop.
• La Popover API es compatible con las versiones actuales de Chrome, Edge, Firefox y Safari. Si tienes que dar soporte a navegadores antiguos, compruébalo antes de depender de ella.
• Cada campo añadido en código debe existir en la definición del formulario, o Ikiform rechaza el envío con un error de campo desconocido.
• No envíes todo el estado de la app. Ruta, versión, cuenta y tamaño responden a la mayoría de preguntas; cualquier otra cosa es una cuestión de privacidad.

Solución de problemas

Preguntas