Componente shadcn/ui

Se o seu projeto usa shadcn/ui, você pode instalar um formulário pronto em vez de escrever o markup. É uma opção entre várias: o mesmo formulário continua funcionando com HTML puro e fetch.

Instalação

npx shadcn@latest add https://ikiform.com/r/form.json

Isso copia components/ikiform/form.tsx para o seu projeto e instala os componentes shadcn/ui que ele usa: button, checkbox, input, label, radio-group e textarea. O arquivo é seu para editar. Os selects usam um <select> nativo, então ele funciona com as versões Radix e Base UI do shadcn/ui.

Uso

import { IkiForm } from "@/components/ikiform/form";

export default function Contact() {
  return <IkiForm form="frm_xxxxxxxxxxxxxxxx" />;
}

Ao montar, o componente busca o schema público do formulário e renderiza um controle por campo, usando os rótulos, placeholders, textos de ajuda e opções que você definiu no painel. Defina os campos primeiro na aba Fields do formulário; um formulário sem campos não renderiza nenhum input.

• Ele valida no navegador com as mesmas regras e mensagens do servidor.
• Ele envia JSON com o honeypot e um timestamp de renderização assinado, o que ajuda na pontuação de spam.
• Erros de campo do servidor aparecem abaixo dos respectivos campos; outros erros aparecem acima do botão.
• Em caso de sucesso, ele substitui o formulário pela mensagem de sucesso do formulário.

Props

import { IkiForm } from "@/components/ikiform/form";

export default function Waitlist() {
  return (
    <IkiForm
      form="frm_xxxxxxxxxxxxxxxx"
      submitLabel="Join the waitlist"
      successMessage="You're on the list."
      onSuccess={({ id }) => console.log("Submitted", id)}
    />
  );
}

Campos no código

Passe fields para renderizar sem a definição do painel. O servidor continua validando contra os campos publicados do formulário, então mantenha os dois em sincronia.

<IkiForm
  form="frm_xxxxxxxxxxxxxxxx"
  fields={[
    { id: "email", type: "email", label: "Work email", required: true },
    { id: "team_size", type: "number", label: "Team size", validation: { min: 1, integer: true } },
  ]}
/>

Verificação humana

Com a verificação de spam definida como Ikiform, o componente incorpora um pequeno frame de ikiform.com que fica oculto até o Turnstile precisar de um clique, e pede um token novo depois de cada tentativa. Se o frame não carregar, ele oferece abrir a verificação em uma nova janela. Com suas próprias chaves do Turnstile, ele renderiza o widget do Turnstile com a site key do formulário.

O endpoint de schema

O componente lê GET https://ikiform.com/f/<formId>/schema. Você pode chamá-lo diretamente para construir seu próprio renderizador, ou usar getSchema do SDK.

{
  "id": "frm_xxxxxxxxxxxxxxxx",
  "title": "Contact",
  "description": null,
  "fields": [{ "id": "email", "type": "email", "label": "Email", "required": true }],
  "settings": { "submit_label": "Send", "success_message": "Thanks!" },
  "honeypot_field": "_gotcha",
  "turnstile_required": false,
  "turnstile_site_key": null,
  "challenge": null,
  "ts": "1792300000000.signature"
}

• Aberto a qualquer origem (Access-Control-Allow-Origin: *) e nunca fica em cache.
• Formulários pausados, desativados e desconhecidos retornam o mesmo 404.
• Só os campos publicados e as configurações de exibição saem do servidor. Domínios permitidos, URL de redirecionamento, configurações de spam e limites de taxa continuam privados.
• challenge é { "provider": "ikiform", "url": ... }, { "provider": "custom", "site_key": ... } ou null. ts é um timestamp de renderização assinado e novo, para enviar de volta como _ikiform_ts.
• Ele permite 60 requisições por minuto por visitante e formulário, separadas da cota de envios.