Getting Started

Get FormForge up and running in your Umbraco project in under five minutes. This guide covers installation, configuration, and building your first form.

Installation

FormForge is distributed as a NuGet package and targets Umbraco 17+ (Bellissima). Install it with the .NET CLI:

dotnet add package FormForge

Or add the package reference directly to your .csproj file:

<PackageReference Include="FormForge" Version="*" />

Run your Umbraco site after installing. FormForge automatically registers itself via IComposer, creates the required database tables through its migration plan, and adds the FormForge section to the backoffice. No manual configuration is required for basic usage.

Configuration

FormForge works out of the box with zero configuration. For production deployments you can fine-tune behavior through appsettings.json keys under the FormForge section.

Available Settings

Example Configuration

{
  "FormForge": {
    "LicenseKey": "-----BEGIN LICENSE-----\n...\n-----END LICENSE-----",
    "TurnstileSiteKey": "0x4AAAAAAA...",
    "TurnstileSecretKey": "0x4AAAAAAA..."
  }
}

If you prefer to keep the license in a separate file, use LicenseFilePath instead:

{
  "FormForge": {
    "LicenseFilePath": "/etc/formforge/license.pem"
  }
}

Rate Limiting

FormForge respects a named rate-limiting policy called "FormSubmission". Your host application is responsible for registering this policy using .NET Core’s built-in rate limiter. If no policy is registered, form submissions are not rate-limited.

// Program.cs
using System.Threading.RateLimiting;

builder.Services.AddRateLimiter(options =>
{
    options.AddFixedWindowLimiter("FormSubmission", opt =>
    {
        opt.PermitLimit = 5;
        opt.Window = TimeSpan.FromMinutes(1);
        opt.QueueProcessingOrder = QueueProcessingOrder.OldestFirst;
        opt.QueueLimit = 0;
    });
});

// ...

app.UseRateLimiter();

Your First Form

With FormForge installed, you can create and publish a working form in a few clicks.

1. Grant Permissions

Before any user can see the FormForge section in the backoffice, their user group needs the FormForge section permission.

1. Go to Settings → User Groups in the Umbraco backoffice.
2. Open the user group you want to grant access to (e.g. Administrators).
3. Under Sections, enable FormForge.
4. Save the user group.

Users in that group will now see the FormForge section in the backoffice sidebar after logging out and back in.

2. Create the Form

1. Open the Umbraco backoffice and navigate to the FormForge section.
2. Click Create Form.
3. Give your form a name and alias (e.g. contact-form).

3. Add Fields

Drag fields from the palette onto the canvas. For a simple contact form, add:

• Text field — label it Name
• Email field — label it Email
• Textarea field — label it Message

4. Configure Settings

Open the Settings tab to customize the submit button label and the success message shown after a visitor submits the form.

5. Save & Publish

Click Save. Your form is now ready to be rendered on any page.

6. Render the Form

There are two ways to add a form to a page:

Option A: FormPicker Property Editor

Add a FormPickerproperty to your document type. Content editors can then select a form from the picker when editing a page. FormForge’s view component renders the selected form automatically.

Option B: ViewComponent (Direct)

Invoke the FormForgeRenderer view component directly in a Razor template:

@await Component.InvokeAsync("FormForgeRenderer", new { formAlias = "contact-form" })

7. Test the Form

Navigate to the page containing your form and submit a test entry. Then return to the backoffice and open the Submissionsinbox under the FormForge section — your entry should appear with all the field data.

Requirements

FormForge has no additional runtime dependencies. All required JavaScript and CSS assets are bundled with the NuGet package and served from the backoffice automatically.