# HTML 폼 제출이 동작하는 방식 > 폼이 제출될 때 브라우저가 하는 일: 어떤 필드를 보내는지, 어떻게 인코딩하는지, 서버가 어떻게 응답해야 하는지, 그리고 Ikiform이 어떻게 응답하는지 설명합니다. 2026-10-25 게시 · https://ikiform.com/ko/guides/html-form-submission 누군가 제출을 누르면 브라우저는 폼의 제약 조건을 확인하고, 이름이 있고 활성화된 모든 컨트롤을 모아 폼의 `enctype`으로 인코딩한 뒤, 폼의 `method`로 `action` URL에 보냅니다. 서버는 일반 페이지 로드처럼 응답하며, 잘 동작하는 서버는 성공한 POST에 `303` 리디렉션으로 응답해 새로고침해도 폼이 두 번 전송되지 않게 합니다. `action`이 Ikiform 같은 폼 백엔드를 가리키게 하면 자체 서버 없이 그 리디렉션, 필드 검증, 스팸 필터링을 얻습니다. HTML 폼은 JavaScript보다 오래되었고 지금도 웹 페이지에서 데이터를 보내는 가장 안정적인 방법입니다. 스크립트가 꺼져 있어도, 느린 휴대폰에서도, 마크업을 붙여 넣을 수 있는 모든 빌더에서 동작합니다. 폼 버그의 대부분은 브라우저가 스스로 하는 일을 모르는 데서 생기므로, 이 가이드는 제출을 단계별로 살펴본 뒤 폼 백엔드가 어디에 들어가는지 보여 줍니다. ## 제출을 누르면 일어나는 일 제출은 본문이 붙은 일반 탐색입니다. 브라우저는 페이지에서 무언가 나가기 전에 네 가지 일을 한 뒤, 요청을 네트워크에 넘기고 돌아오는 것을 불러옵니다. 다이어그램: 제출 클릭과 다음 페이지 사이에 브라우저가 하는 일 1. 제출 버튼, 텍스트 필드의 Enter 키, 또는 form.requestSubmit()이 제출을 시작하고 submit 이벤트를 발생시킵니다. 2. 폼에 novalidate가 없으면 브라우저가 모든 컨트롤의 제약 조건을 확인합니다. 첫 번째로 유효하지 않은 컨트롤에 메시지가 표시되고 아무것도 전송되지 않습니다. 3. 브라우저가 이름이 있고 비활성화되지 않은 모든 컨트롤로 폼 데이터 세트를 만듭니다. 4. 따로 지정하지 않으면 urlencoded인 폼의 enctype으로 그 세트를 인코딩합니다. 5. 폼의 method로 action URL에 이동하며 본문을 보냅니다. 6. 서버가 응답합니다. 303은 브라우저에 다른 URL을 GET으로 불러오라고 알리며, 방문자가 최종적으로 보게 되는 페이지가 됩니다. 선 위의 모든 일은 네트워크 없이 일어납니다. submit 이벤트 리스너는 첫 단계에서 흐름을 멈추고 fetch로 넘겨받을 수 있습니다. ## 요청을 결정하는 속성 `
`의 다섯 가지 속성이 데이터가 어디로 어떻게 가는지 정합니다. 각각은 대응하는 `form*` 속성으로 버튼 하나에 대해 덮어쓸 수 있으며, 그래서 한 폼에 서로 다르게 동작하는 **Send**와 **Save draft** 버튼을 둘 수 있습니다. | 속성 | 기본값 | 하는 일 | 버튼별 덮어쓰기 | | --- | --- | --- | --- | | `action` | 페이지 자체의 URL | 데이터를 받는 URL입니다. 상대 값은 페이지를 기준으로 해석됩니다. [action 속성](https://ikiform.com/ko/guides/html-form-submission/action-attribute.md)을 참고하세요 | `formaction` | | `method` | `get` | `get`은 필드를 URL의 쿼리 문자열에 넣습니다. `post`는 본문으로 보냅니다. `dialog`는 아무것도 보내지 않고 ``를 닫습니다 | `formmethod` | | `enctype` | `application/x-www-form-urlencoded` | `post` 본문을 인코딩하는 방식입니다. 파일에는 `multipart/form-data`가 필요합니다. `text/plain`은 디버깅용입니다 | `formenctype` | | `novalidate` | 끔 | 제출 시 브라우저의 제약 조건 확인을 건너뜁니다 | `formnovalidate` | | `target` | `_self` | 응답이 불러와지는 곳입니다. `_blank`는 새 탭을 열고, 이름이 있는 iframe은 페이지를 그대로 둡니다 | `formtarget` | 버튼 두 개, 동작 두 가지. 두 번째 버튼은 검증을 건너뛰며, 클릭한 버튼의 `name`과 `value`가 데이터에 추가되므로 서버는 어느 버튼이 눌렸는지 압니다. `제출 버튼 두 개`: ```html ``` ### 전송되는 컨트롤 브라우저는 HTML 명세가 폼 데이터 세트라고 부르는 것만 보냅니다. 제출 로그의 놀라운 점 대부분은 다음 규칙에서 옵니다. - 컨트롤에는 `name`이 필요합니다. `id`만 있으면 아무것도 보내지 않습니다. - `disabled` 컨트롤은 건너뜁니다. 값을 보여 주고 잠그면서 보내려면 `readonly`를 쓰세요. - 체크하지 않은 체크박스나 라디오는 `false`가 아니라 아무것도 보내지 않습니다. `value`가 없는 체크된 체크박스는 `on`을 보냅니다. - 폼을 제출한 버튼만 `name`과 `value`와 함께 포함됩니다. - ` ``` **Next.js** 서버 액션이 `FormData`를 받아 시크릿 키와 함께 JSON으로 전달하고 Ikiform의 필드 오류를 반환합니다. `useActionState`가 각 메시지를 해당 입력 아래에 두고 방문자가 입력한 내용을 유지합니다. `app/report/actions.ts`: ```ts "use server"; import { headers } from "next/headers"; export interface ReportState { sent: boolean; fields: Record; message: string; values: Record; } const NAMES = ["email", "page", "severity", "details"] as const; export async function sendReport(_previous: ReportState, formData: FormData): Promise { const values = Object.fromEntries(NAMES.map((name) => [name, String(formData.get(name) ?? "").trim()])); const origin = (await headers()).get("origin"); const response = await fetch("https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx", { method: "POST", headers: { Accept: "application/json", "Content-Type": "application/json", Authorization: `Bearer ${process.env.IKIFORM_SECRET_KEY}`, ...(origin ? { Origin: origin } : {}), }, body: JSON.stringify({ ...values, _gotcha: String(formData.get("_gotcha") ?? "") }), }); const result = await response.json().catch(() => null); if (result?.ok) return { sent: true, fields: {}, message: "Thanks. We'll look at that page today.", values: {} }; return { sent: false, fields: result?.error?.fields ?? {}, message: result?.error?.message ?? "The report didn't go through. Try again.", values, }; } ``` `app/report/report-form.tsx`: ```tsx "use client"; import { useActionState } from "react"; import { type ReportState, sendReport } from "./actions"; const initial: ReportState = { sent: false, fields: {}, message: "", values: {} }; function FieldError({ id, messages }: { id: string; messages?: string[] }) { return messages?.length ?

{messages[0]}

: null; } export function ReportForm() { const [state, action, pending] = useActionState(sendReport, initial); if (state.sent) return

{state.message}

; return (
{fields.details &&

{fields.details[0]}

} )} ``` **TanStack Start** POST 서버 함수가 `.validator()`에서 `FormData`를 읽고 필드 오류를 일반 데이터로 반환하므로, 컴포넌트는 아무것도 catch하지 않고 이를 렌더링할 수 있습니다. `src/routes/report.tsx`: ```tsx import { createFileRoute } from "@tanstack/react-router"; import { createServerFn, useServerFn } from "@tanstack/react-start"; import { getRequestHeader } from "@tanstack/react-start/server"; import { type FormEvent, useState } from "react"; type Outcome = { sent: boolean; fields: Record; message: string }; const sendReport = createServerFn({ method: "POST" }) .validator((data: unknown) => { if (!(data instanceof FormData)) throw new Error("Expected form data"); const read = (name: string) => String(data.get(name) ?? "").trim(); return { email: read("email"), page: read("page"), severity: read("severity"), details: read("details"), _gotcha: read("_gotcha"), }; }) .handler(async ({ data }): Promise => { const origin = getRequestHeader("origin"); const response = await fetch("https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx", { method: "POST", headers: { Accept: "application/json", "Content-Type": "application/json", Authorization: `Bearer ${process.env.IKIFORM_SECRET_KEY}`, ...(origin ? { Origin: origin } : {}), }, body: JSON.stringify(data), }); const result = await response.json(); if (result.ok) return { sent: true, fields: {}, message: "Thanks. We'll look at that page today." }; return { sent: false, fields: result.error.fields ?? {}, message: String(result.error.message) }; }); export const Route = createFileRoute("/report")({ component: Report }); function Report() { const send = useServerFn(sendReport); const [outcome, setOutcome] = useState(null); const [pending, setPending] = useState(false); async function onSubmit(event: FormEvent) { event.preventDefault(); setPending(true); try { setOutcome(await send({ data: new FormData(event.currentTarget) })); } catch { setOutcome({ sent: false, fields: {}, message: "The report didn't go through. Try again." }); } finally { setPending(false); } } if (outcome?.sent) return

{outcome.message}

; const fields = outcome?.fields ?? {}; return (
{fields.email ?

{fields.email[0]}

: null} {fields.page ?

{fields.page[0]}

: null} {#if fields.details}

{fields.details[0]}

{/if}
{/if} ``` **Nuxt** 서버 라우트가 `NUXT_IKIFORM_SECRET_KEY`로 설정되는 `runtimeConfig.ikiformSecretKey`로 신고를 전달합니다. 필드 오류를 `data`에 담아 `createError`를 throw하며, `$fetch`가 클라이언트에서 이를 돌려줍니다. `server/api/report.post.ts`: ```ts export default defineEventHandler(async (event) => { const body = await readBody>(event); const { ikiformSecretKey } = useRuntimeConfig(event); const origin = getRequestHeader(event, "origin"); const response = await fetch("https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx", { method: "POST", headers: { Accept: "application/json", "Content-Type": "application/json", Authorization: `Bearer ${ikiformSecretKey}`, ...(origin ? { Origin: origin } : {}), }, body: JSON.stringify({ email: body.email ?? "", page: body.page ?? "", severity: body.severity ?? "", details: body.details ?? "", _gotcha: body._gotcha ?? "", }), }); const result = await response.json(); if (!result.ok) { throw createError({ status: response.status, message: String(result.error.message), data: { fields: result.error.fields ?? {} }, }); } return { sent: true }; }); ``` `app/components/ReportForm.vue`: ```vue