> ## Documentation Index
> Fetch the complete documentation index at: https://docs.declarativeforms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a form

> Create a form in YAML, store it in GitHub, and share it as a live URL — in under three minutes.

Define a form in a YAML file, push it to a GitHub repository, and Declarative Forms turns it into a live, shareable form. This page covers the YAML-first workflow; Studio is also available if you prefer a visual editor.

<Info>
  **All you need is a GitHub repository.** Public or private — both work. There is nothing to install, sign up for, or deploy.
</Info>

## How it works

```mermaid theme={null}
graph LR
  A[YAML file in GitHub] --> B[frms.dev renders the form]
  B --> C[Shareable URL]
```

You create a `.yaml` file in a GitHub repository. Declarative Forms reads that file and renders it as an interactive form at a `frms.dev` URL. Every time you update the YAML and push to `main`, the form updates automatically.

***

## Create your form

<Steps>
  <Step title="Create a YAML file">
    In any GitHub repository, create a new `.yaml` file on the `main` branch. The filename becomes part of the form URL — for example, `contact.yaml` becomes `/contact`.
  </Step>

  <Step title="Define the form">
    Paste this complete contact form into your YAML file:

    ```yaml contact.yaml theme={null}
    version: 1
    title: "Contact us"
    description: "Send us a message and we will get back to you."

    sections:
      - id: contact
        title: "Your details"
        fields:
          - id: full_name
            type: short_text
            label: "Full name"
            placeholder: "Jane Smith"
            validators:
              - required

          - id: email
            type: email
            label: "Email address"
            placeholder: "jane@example.com"
            validators:
              - required

          - id: message
            type: long_text
            label: "Message"
            placeholder: "How can we help?"
            validators:
              - required

        next: done

    connections:
      - type: email
        to: "hello@example.com"
        subject: "New contact form submission"
        include_responses: true
    ```

    Replace `hello@example.com` with the email address where you want to receive submissions.
  </Step>

  <Step title="Commit and push">
    Commit the file to the `main` branch and push. Your form is now live.
  </Step>
</Steps>

***

## Open your form

Once your YAML file is on `main`, open it through `frms.dev`. The process differs slightly depending on whether your repository is public or private.

<Tabs>
  <Tab title="Public repository">
    Navigate directly to:

    ```text theme={null}
    https://frms.dev/<owner>/<repo>/<filename>
    ```

    | Placeholder  | Value                                |
    | ------------ | ------------------------------------ |
    | `<owner>`    | Your GitHub username or organization |
    | `<repo>`     | The repository name                  |
    | `<filename>` | The YAML filename without `.yaml`    |

    **Example:** If your GitHub username is `acme` and you created `contact.yaml` in the `forms` repository:

    ```text theme={null}
    https://frms.dev/acme/forms/contact
    ```

    The form loads immediately. No authentication required — anyone with the link can fill it in.
  </Tab>

  <Tab title="Private repository">
    Use the same URL format:

    ```text theme={null}
    https://frms.dev/<owner>/<repo>/<filename>
    ```

    The first time **you** (the form creator) open this URL, Declarative Forms will redirect you to GitHub to authorize access. This is a one-time OAuth flow — you grant Declarative Forms read access to the repository so it can fetch the YAML file.

    Once authorized, the form loads and you are redirected to a short URL with a unique form ID (e.g., `https://frms.dev/c979ac5b`). This is the link you share with your audience.

    <Note>
      **Your respondents will never be asked to log into GitHub.** The OAuth authorization is only required once — by you, the form creator — so that Declarative Forms can connect to your private repository and read the YAML file. After that, anyone with the short URL can fill in the form without any authentication.
    </Note>
  </Tab>
</Tabs>

***

## Share your form

After you load the form for the first time, you'll be redirected to a permanent short URL like:

```text theme={null}
https://frms.dev/c979ac5b
```

This is your form's **shareable link**. Share it with anyone who should fill in the form. It always points to the latest version of your YAML — every push to `main` updates the form automatically.

<Info>
  **This is the URL your respondents use — not the repository path.** The short URL works without any GitHub authentication, even if the YAML file lives in a private repository. Only you (the form creator) needed to authorize access; your audience simply opens the link and fills in the form.
</Info>

<Check>
  **No redeploy needed.** Edit the YAML, push to `main`, and the form updates. There is no build step, deploy step, or cache to clear.
</Check>

***

## Verify it works

Open your form URL and run through these checks:

<Steps>
  <Step title="Form loads">
    The title, description, and all fields should appear.
  </Step>

  <Step title="Validation works">
    Submit with empty required fields — each one should show an error.
  </Step>

  <Step title="Submission succeeds">
    Fill in every field and submit. You should see the default completion screen.
  </Step>

  <Step title="Email arrives">
    Check the inbox you configured. A submission email with all responses should arrive within a few minutes.
  </Step>
</Steps>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Form not loading">
    * Confirm the file is on the `main` branch.
    * Check that the URL matches the filename exactly (without `.yaml`).
    * For private repos, make sure you've completed the GitHub authorization.
  </Accordion>

  <Accordion title="YAML parse error">
    * Use **spaces**, not tabs. YAML is whitespace-sensitive.
    * Ensure all strings with special characters (`:`, `#`, `"`) are wrapped in quotes.
    * Validate your YAML with an online linter like [yamllint.com](https://www.yamllint.com).
  </Accordion>

  <Accordion title="No submission email received">
    * Confirm you replaced `hello@example.com` with your actual email address.
    * Check your spam or junk folder.
    * Verify the `connections` block is at the top level of the YAML (not nested inside a section).
  </Accordion>

  <Accordion title="Changes not showing up">
    * Make sure you pushed to the `main` branch, not a different branch.
    * Hard-refresh the form page (`Cmd+Shift+R` or `Ctrl+Shift+R`) to bypass browser cache.
  </Accordion>
</AccordionGroup>