shadcn/ui 컴포넌트

프로젝트에서 shadcn/ui를 쓴다면 마크업을 직접 작성하는 대신 미리 만들어진 폼을 설치할 수 있습니다. 여러 선택지 중 하나일 뿐이며, 같은 폼은 일반 HTML이나 fetch로도 계속 작동합니다.

설치

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

이 명령은 components/ikiform/form.tsx를 프로젝트에 복사하고, 사용하는 shadcn/ui 컴포넌트인 button, checkbox, input, label, radio-group, textarea를 설치합니다. 파일은 자유롭게 수정할 수 있습니다. 선택 상자는 네이티브 <select>를 사용하므로 shadcn/ui의 Radix 버전과 Base UI 버전 모두에서 작동합니다.

사용법

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

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

컴포넌트는 마운트될 때 폼의 공개 스키마를 가져와, 대시보드에서 설정한 레이블, 플레이스홀더, 도움말, 옵션을 사용해 필드마다 컨트롤을 하나씩 렌더링합니다. 먼저 폼의 필드 탭에서 필드를 정의하세요. 필드가 없는 폼은 입력을 렌더링하지 않습니다.

• 서버와 같은 규칙과 메시지로 브라우저에서 검증합니다.
• 허니팟과 서명된 렌더링 타임스탬프를 포함해 JSON으로 POST하므로 스팸 점수 산정에 도움이 됩니다.
• 서버의 필드 오류는 해당 필드 아래에, 다른 오류는 버튼 위에 표시됩니다.
• 성공하면 폼을 폼의 성공 메시지로 바꿉니다.

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)}
    />
  );
}

코드로 필드 정의하기

대시보드의 정의 없이 렌더링하려면 fields를 전달하세요. 서버는 여전히 폼에 게시된 필드로 검증하므로 둘을 맞춰 두세요.

<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 } },
  ]}
/>

사람 확인

스팸 검사가 Ikiform으로 설정되어 있으면, 컴포넌트가 Turnstile에 클릭이 필요할 때까지 숨겨져 있는 작은 ikiform.com 프레임을 임베드하고, 시도할 때마다 새 토큰을 요청합니다. 프레임을 불러올 수 없으면 새 창에서 확인을 열도록 안내합니다. 직접 발급한 Turnstile 키를 쓰면 폼의 사이트 키로 Turnstile 위젯을 렌더링합니다.

스키마 엔드포인트

컴포넌트는 GET https://ikiform.com/f/<formId>/schema를 읽습니다. 직접 렌더러를 만들려면 이 엔드포인트를 호출하거나, SDK의 getSchema를 사용하세요.

{
  "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"
}

• 모든 출처에 열려 있고(Access-Control-Allow-Origin: *) 캐시되지 않습니다.
• 일시 중지되었거나, 비활성화되었거나, 알 수 없는 폼은 모두 같은 404를 반환합니다.
• 게시된 필드와 표시 설정만 서버 밖으로 나갑니다. 허용 도메인, 리디렉션 URL, 스팸 설정, 레이트 리밋은 비공개로 유지됩니다.
• challenge는 { "provider": "ikiform", "url": ... }, { "provider": "custom", "site_key": ... } 또는 null입니다. ts는 _ikiform_ts로 돌려보낼 새로 서명된 렌더링 타임스탬프입니다.
• 제출 허용량과 별도로, 방문자와 폼별로 분당 60건의 요청을 허용합니다.