Ninja Form Kit

Elevate your form development with Ninja Form Kit, a powerful TypeScript library that seamlessly integrates with your theme. This robust toolkit unifies UI generation and form validation into a single configuration object, streamlining your workflow. Leverage type-safe components to create polished, responsive forms with minimal effort. From basic inputs to complex layouts, Ninja Form Kit empowers developers to build professional, user-friendly forms while maintaining code consistency across projects. Simplify your form creation process and enhance productivity with our comprehensive, TypeScript-first solution.

Table of Contents

• Ninja Form Kit
  • Table of Contents
  • Installation
  • Quick Start
    • Define the config in loader
    • Use the Form in your template/component
    • Validate the form with actions
    • Form Config Options
    • FormField Options
  • Validation
    • Validation Options
  • Theming
  • More examples
    • Register Form
    • Login Form
  • License

Installation

To install Ninja Form Kit, use npm or yarn:

npm install ninjaformkit
# or
yarn add ninjaformkit

Quick Start

To configure your form, define a formConfig object in your +page.server.ts file. This object allows you to specify form properties such as method, action, fields, and validation rules. For optimal type safety, ensure your formConfig adheres to the FormConfig interface. Important: Define formConfig outside the load function to guarantee accessibility within actions.

Define the config in loader

import { type FormConfig } from 'ninjaformkit'

const formConfig = {
	method: 'post',
	fields: {
		email: {
			type: 'text',
			variant: 'email',
			placeholder: 'Enter your email...',
			label: 'Email',
			validate: {
				required: true,
				isEmail: true
			}
		},
		message: {
			type: 'textarea',
			placeholder: 'Enter your message...',
			label: 'Message',
			validate: {
				required: true,
				minLength: 10,
				maxLength: 500
			}
		},
		submit: {
			type: 'submit',
			label: 'Submit'
		}
	}
} satisfies FormConfig;

export const load: PageServerLoad = async () => {
	return { formConfig };
};

Use the Form in your template/component

<script lang="ts">
    import { Form } from 'ninjaformkit'
    export let data;
</script>

<Form config={data.formConfig} />

Validate the form with actions

import { validate } from 'ninjaformkit'

export const actions = {
	default: async ({ request }) => {
		const { errors, hasErrors, values } = await validate(request, formConfig);

		if (hasErrors) {
                        // Errors will appears under each input that validation fails
			return fail(400, { errors });
		}

	// Process the type safe form values 
        await sendEmail({
            email: values.email, // string
            message: values.message // string
        });
        
        return redirect(301, '/');
 
	}
} satisfies Actions;

Form Config Options

The formConfig object allows you to configure various aspects of your form. Below is a table explaining each option:

| Option | Type | Description | |-------------|----------------------------------------------------------------------|-----------------------------------------------------------------------------------------------| | action | string | The URL to which the form data will be submitted. Optional. | | encType | 'application/x-www-form-urlencoded' \| 'multipart/form-data' \| 'text/plain' | The encoding type for the form. Optional. | | method | 'get' \| 'post' | The HTTP method to use when submitting the form. Required. | | fields | Record<string, FormField> | An object where each key is a field name and the value is a FormField object. Required. | | runLoader | boolean | Denotes weather to run sveltekits invalidateAll hook. Optional

FormField Options

Each field in the fields object is a FormField with the following options:

| Option | Type | Description | |-----------------|----------------------------------------------------------------------|-----------------------------------------------------------------------------------------------| | type | 'text' \| 'textarea' \| 'submit' \| 'checkbox' \| 'radio' \| 'toggle' \| 'select' \| 'file' | The type of the form field. Required. | | label | string | The label for the form field. Required. | | defaultValue | string \| number \| null | The default value for the form field. Optional. | | defaultChecked| boolean | The default checked state for checkbox, radio, or toggle fields. Optional. | | width | 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 11 \| 12 | The width of the form field, used for fieldset grid layout. Optional. Defaults to 12. | | variant | 'password' \| 'email' \| 'text' \| 'color' \| 'number' | The variant of the form field, specifying a more specific type. Works with the "text" input type. Defaults to "text". Optional. | | placeholder | string | The placeholder text for the form field. Optional. | | multiple | boolean | Whether the field allows multiple values (e.g., for file and select inputs). Optional. | | break | boolean | Weather to break into a new row in grid. Optional. | | icon | string | An icon to display with the form field. This relies on @iconify library (e.g. material-symbols:verified-user) Optional. | | options | { value: string \| number; label: string; }[] | An array of options for select and radio fields. Each option has a value and a label. Optional. Note Select and Radio inputs will throw an error if these values are not set. | | disabled | boolean | Whether the form field is disabled. Optional. | | before | string | Content to display before the form field. Optional. | | after | string | Content to display after the form field. Optional. | | validate | object | Validation rules for the form field. Optional.

Validation

Ninja Form Kit currently has 19 validate options.

Validation Options

The validate object allows you to specify validation rules for the form field. Below is a table explaining each option:

| Option | Type | Description | |-------------------|---------------|-----------------------------------------------------------------------------------------------| | required | boolean | Whether the field is required. | | minLength | number | The minimum length of the field value. | | maxLength | number | The maximum length of the field value. | | min | number | The minimum value for numeric fields. | | max | number | The maximum value for numeric fields. | | isEmail | boolean | Whether the field value should be a valid email address. | | isUrl | boolean | Whether the field value should be a valid URL. | | isNumber | boolean | Whether the field value should be a valid number. | | isFloat | boolean | Whether the field value should be a valid float. | | isAlpha | boolean | Whether the field value should contain only alphabetic characters. | | isAlphanumeric | boolean | Whether the field value should contain only alphanumeric characters. | | isDate | boolean | Whether the field value should be a valid date. | | isTime | boolean | Whether the field value should be a valid time. | | isDateTime | boolean | Whether the field value should be a valid date-time. | | mimeTypes | Array<string>| An array of acceptable MIME types for file inputs. | | maxSize | number | The maximum file size for file inputs, in bytes. | | matches | string | A regex pattern that the field value should match. | | badPasswordCheck| boolean | Whether to check the field value against a list of common bad passwords. Utilises pwned passwords API. |

Theming

Ninja Form Kit offers a wide array of customizable CSS variables. Simply import the CSS file into your +layout.svelte and tailor the variables to perfectly match your theme.

:root {
    --nfk-font: ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
    --nfk-default: #005f8b; // Button, radio and toggle colours
    --nfk-default-hover: #0a5171; // Button, radio and toggle colours hover
    --nfk-text: #000000; // text colour for labels
    --nkf-input-bg: #f3f4f6; // Back ground colour for form inputs
    --nkf-input-bg-file-hover: #f3f4f6; // Hover state for file input
    --nfk-button-text: #ffffff; // Text colout for buttons and radio
    --nkf-placeholder: #a0aec0; // Placeholder text colour
    --nfk-border: #e2e8f0; // Input border
    --nkf-error: #e53e3e; // Error color for border and error text
    --nkf-required: #e84949; // Required asterix on inouts with validation rules
    --nfk-outline: #0073aa; // Outline for inout focused
    --nfk-gap-x: 14px; // Gap between inputs row
    --nfk-gap-y: 14px; // Gap between inputs colun
}

@media (prefers-color-scheme: dark) {
    :root {
        --nfk-default: #005f8b;
        --nfk-text: #FFFFFF;
        --nkf-input-bg: #35383c;
        --nkf-input-bg-file-hover: #595c61;
        --nfk-button-text: #ffffff;
        --nkf-placeholder: #dfe3e7;
        --nfk-border: #e2e8f0;
        --nkf-error: #e53e3e;
        --nkf-required: #e84949;
        --nfk-outline: #0073aa;
        --nkf-btn-text: #ffffff;
    }
}

More examples

Register Form

const formConfig = {
	method: 'post',
	fields: {
		username: {
			type: 'text',
			label: 'Username',
			placeholder: 'Enter your username...',
			width: 5,
			validate: {
				required: true,
				minLength: 3,
				maxLength: 20
			}
		},
		email: {
			type: 'text',
			variant: 'email',
			label: 'Email',
			placeholder: 'Enter your email...',
			width: 7,
			validate: {
				required: true,
				isEmail: true
			}
		},
		referer: {
			type: 'select',
			label: 'Referer',
			placeholder: 'Select an option...',
			width: 4,
			options: [
				{ label: 'Google', value: 'google' },
				{ label: 'Friend', value: 'friend' },
				{ label: 'Other', value: 'other' }
			],
			break: true,
			validate: {
				required: true
			}
		},
		accountType: {
			type: 'radio',
			label: 'Account Type',
			width: 8,
			options: [
				{ label: 'Personal', value: 'personal' },
				{ label: 'Business', value: 'business' }
			],
			validate: {
				required: true
			}
		},
		password: {
			type: 'text',
			variant: 'password',
			label: 'Password',
			placeholder: 'Enter your password...',
			width: 6,
			validate: {
				required: true,
				minLength: 8,
				badPasswordCheck: true
			}
		},
		confirmPassword: {
			type: 'text',
			variant: 'password',
			label: 'Confirm Password',
			placeholder: 'Confirm your password...',
			width: 6,
			validate: {
				required: true,
				matches: 'password'
			}
		},
		newsletter: {
			type: 'checkbox',
			label: 'Subscribe to newsletter',
			defaultChecked: true
		},
		submit: {
			type: 'submit',
			label: 'Submit'
		}
	}
} satisfies FormConfig;

Login Form

const formConfig = {
	method: 'post',
	fields: {
		email: {
			type: 'text',
			variant: 'email',
			placeholder: 'Enter your email...',
			label: 'Email',
			validate: {
				required: true,
				isEmail: true
			},
                        after: `<a href="/reset-password" class="text-sm mt-3 text-right">Forgot Password</a>`
		},
		password: {
			type: 'text',
			variant: 'password',
			placeholder: 'Enter your password...',
			label: 'Password',
			validate: {
				required: true
			}
		},
		rememberMe: {
			type: 'checkbox',
			label: 'Remember me'
		},
		submit: {
			type: 'submit',
			label: 'Submit'
		}
	}
} satisfies FormConfig;

License

This project is licensed under the MIT License. See the LICENSE file for details.