Form Component

The form component displays input fields that users can fill in. When submitted, the data is posted to an SQL file where you can insert it into the database, perform searches, or process it with SQL queries.

Basic Usage

SELECT 'form' AS component;
SELECT 'username' AS name;
SELECT 'email' AS name, 'email' AS type;

Handling Form Data

When a form is submitted, values are available as SQL parameters in the target page. A field named “username” becomes :username in your SQL query.

-- In the form page (users.sql)
SELECT 'form' AS component, 'create_user.sql' AS action;
SELECT 'username' AS name;

-- In the handler page (create_user.sql)
INSERT INTO users(name) VALUES(:username)
RETURNING 'redirect' AS component, 'users.sql' AS link;

Top-Level Properties

title

text

Name to display at the top of the form in larger font

action

url

Link to the target SQL file that handles form submission. Defaults to the current page with the form’s id as hash.

method

text

default:"post"

Set to ‘GET’ to pass form contents as URL parameters (e.g., target.sql?x=v). Use POST for sensitive data.

validate

text

default:"Submit Query"

Text for the submit button. Set to empty string to remove the button completely.

validate_color

color

default:"primary"

Color of the submit button (e.g., primary, green, red, blue)

validate_outline

color

Outline color for the submit button

validate_icon

icon

Icon to display on the left side of the submit button

validate_shape

text

Shape of the submit button (e.g., pill, square)

validate_size

text

Size of the submit button (e.g., sm, lg)

reset

text

Text for the reset button. Omit to hide the reset button.

reset_color

color

Color of the reset button

reset_icon

icon

Icon for the reset button

text

Unique identifier for the form. Use with the button component to submit from outside the form.

auto_submit

boolean

Automatically submit when any field changes. Removes the submit button.

enctype

text

Encoding type when method is POST. Automatically set to multipart/form-data for file uploads.

Field Properties

name

text

required

Field identifier used to retrieve the value in the target page (e.g., :fieldname)

type

text

default:"text"

Input type: text, number, email, password, tel, url, date, time, datetime-local, month, week, color, range, file, textarea, select, radio, checkbox, switch, hidden, header, submit

label

text

Friendly name displayed to the user. Defaults to the field name.

placeholder

text

Placeholder text shown when the field is empty

value

text

Default value pre-filled in the field

description

text

Helper text displayed near the input field

description_md

text

Helper text in Markdown format with bold, italics, links

required

boolean

Prevent form submission if this field is empty

width

integer

default:"12"

Field width from 1-12. Use smaller values to place fields side-by-side.

autofocus

boolean

Automatically focus this field when the page loads

disabled

boolean

Makes the field non-editable and not submitted with the form

readonly

boolean

Prevents editing but the value is still submitted

class

text

CSS class to apply to the form element

text

HTML identifier for JavaScript manipulation or styling

Text Input Properties

minlength

integer

Minimum text length allowed

maxlength

integer

Maximum text length allowed

pattern

text

Regular expression the value must match (e.g., [0-9]{3} for 3 digits)

autocomplete

boolean

Whether the browser should suggest previously entered values

prefix

text

Text to display on the left side of the input

prefix_icon

icon

Icon to display on the left side of the input

suffix

text

Text to display on the right side (e.g., currency symbol, units)

Number Input Properties

min

number

Minimum value for number inputs

max

number

Maximum value for number inputs

step

number

Increment value for number inputs. Set to 1 for integers only.

Textarea Properties

rows

integer

default:"3"

Number of visible text rows for textarea

Select Properties

options

json

required

JSON array of objects with label, value, and optional selected properties

empty_option

text

Adds an empty option with the given label before other options

multiple

boolean

Allow selecting multiple options. Use square brackets in name: my_field[]

searchable

boolean

Display with a dropdown that allows searching for options

Alias for searchable

create_new

boolean

Allow users to enter new values not in the options list

options_source

url

URL to dynamically load options as the user types. Returns JSON with value and label.

Checkbox and Radio Properties

checked

boolean

Whether the checkbox or radio button appears checked

File Upload Properties

text

Allowed file types (e.g., image/png, image/jpeg, .pdf)

Access uploaded files using sqlpage.uploaded_file_path.

Examples

Basic Registration Form

SELECT 'form' AS component,
       'User Registration' AS title,
       'Create Account' AS validate;

SELECT 'First name' AS name, 'John' AS placeholder;
SELECT 'Last name' AS name, true AS required;
SELECT 'Email' AS name, 'email' AS type, true AS required;
SELECT 'Password' AS name, 'password' AS type, true AS required,
       '**Minimum 8 characters**, at least one letter & one number' AS description_md;
SELECT 'I accept the terms' AS label, 'terms' AS name,
       'checkbox' AS type, true AS required;

Multi-Column Layout

SELECT 'form' AS component;

SELECT 'first_name' AS name, 'First name' AS label, 4 AS width;
SELECT 'middle_name' AS name, 'Middle name' AS label, 4 AS width;
SELECT 'last_name' AS name, 'Last name' AS label, 4 AS width;

SELECT 'form' AS component;

SELECT 'select' AS type,
       'fruit' AS name,
       'Select a fruit...' AS empty_option,
       json_group_array(json_object(
           'label', name,
           'value', id
       )) AS options
FROM fruits;

Radio Buttons

SELECT 'form' AS component, 'GET' AS method;

SELECT 'component' AS name, 'radio' AS type,
       'form' AS value, 'Form' AS label,
       'Read user input in SQL' AS description;
       
SELECT 'component' AS name, 'radio' AS type,
       'map' AS value, 'Map' AS label, true AS checked,
       'Display maps from database data' AS description;

Toggle Switches

SELECT 'form' AS component;

SELECT 'switch' AS type,
       'dark_mode' AS name,
       'Dark theme' AS label,
       'Enable dark theme' AS description;

SELECT 'switch' AS type,
       'notifications' AS name,
       'Enable notifications' AS label,
       true AS checked;

File Upload

SELECT 'form' AS component,
       'multipart/form-data' AS enctype,
       'Upload' AS validate,
       'handle_upload.sql' AS action;

SELECT 'my_file' AS name,
       'file' AS type,
       'Picture' AS label,
       'image/png, image/jpeg' AS accept,
       true AS required;

Handle the upload in handle_upload.sql:

INSERT INTO uploaded_file(name, data)
VALUES (
    :my_file,
    sqlpage.read_file_as_data_url(
        sqlpage.uploaded_file_path('my_file')
    )
);

SELECT 'redirect' AS component, 'index.sql' AS link;

Auto-Submit on Change

SELECT 'form' AS component,
       true AS auto_submit;

SELECT 'select' AS type,
       'component' AS name,
       'Component' AS label,
       json('[{"label":"Form","value":"form","selected":true},{"label":"Map","value":"map"}]') AS options;

Form with External Submit Buttons

SELECT 'form' AS component,
       'poem' AS id,
       '' AS validate;

SELECT 'textarea' AS type,
       'poem' AS name,
       'Write a poem' AS placeholder;

SELECT 'button' AS component;
SELECT '?action=save' AS link,
       'poem' AS form,
       'Save' AS title,
       'primary' AS color;
SELECT '?action=preview' AS link,
       'poem' AS form,
       'Preview' AS title,
       'yellow' AS outline;

Input with Prefix and Suffix

SELECT 'form' AS component;

SELECT 'email' AS name,
       'Your account' AS label,
       'mail' AS prefix_icon,
       'Email:' AS prefix,
       '@mydomain.com' AS suffix;

SELECT 'price' AS name,
       'number' AS type,
       'Price' AS label,
       '$' AS prefix,
       'USD' AS suffix;

Form with Headers

SELECT 'form' AS component,
       'Person Information' AS title;

SELECT 'header' AS type, 'Identity' AS label;
SELECT 'Name' AS name;
SELECT 'Surname' AS name;

SELECT 'header' AS type, 'Contact' AS label;
SELECT 'phone' AS name, 'Phone number' AS label;
SELECT 'Email' AS name;

Hidden Fields

SELECT 'form' AS component,
       'Delete' AS validate,
       'red' AS validate_color;

SELECT 'hidden' AS type,
       'resource_id' AS name,
       '1234' AS value;

SELECT 'confirm' AS name,
       'Type "DELETE" to confirm' AS label,
       true AS required;

All Input Types

Text-Based Inputs

text: Single-line text input (default)
email: Email address with validation
password: Masked password input
tel: Telephone number
url: Web address with validation
search: Search input
textarea: Multi-line text input

Number Inputs

number: Numeric input with increment controls
range: Slider for selecting a value

Date and Time

date: Date picker
time: Time picker
datetime-local: Date and time picker
month: Month and year picker
week: Week picker

Selection

select: Dropdown menu
radio: Radio button (one choice from a group)
checkbox: Checkbox (multiple choices)
switch: Toggle switch (SQLPage custom type)

File

file: File upload input

Other

color: Color picker
hidden: Hidden field (not visible to users)
header: Section header (SQLPage custom type)
submit: Submit button within the form

Security Notes

Always use parameterized queries (:parameter) to prevent SQL injection
Use POST method for sensitive data
Validate and sanitize user input in your SQL queries
Don’t commit files with secrets like .env or credentials.json

button - Submit forms from outside with the form property
authentication - Protect forms with login

Overview

Display Components

Input Components

Layout Components

Special Components

Basic Usage

Handling Form Data

Top-Level Properties

Field Properties

Text Input Properties

Number Input Properties

Textarea Properties

Select Properties

Checkbox and Radio Properties

File Upload Properties

Examples

Basic Registration Form

Multi-Column Layout

Radio Buttons

Toggle Switches

File Upload

Auto-Submit on Change

Form with External Submit Buttons

Input with Prefix and Suffix

Form with Headers

Hidden Fields

All Input Types

Text-Based Inputs

Number Inputs

Date and Time

Selection

File

Other

Security Notes

Build docs developers (and LLMs) love

Overview

Display Components

Input Components

Layout Components

Special Components

​Basic Usage

​Handling Form Data

​Top-Level Properties

​Field Properties

​Text Input Properties

​Number Input Properties

​Textarea Properties

​Select Properties

​Checkbox and Radio Properties

​File Upload Properties

​Examples

​Basic Registration Form

​Multi-Column Layout

​Select Dropdown from Database

​Radio Buttons

​Toggle Switches

​File Upload

​Auto-Submit on Change

​Form with External Submit Buttons

​Input with Prefix and Suffix

​Form with Headers

​Hidden Fields

​All Input Types

​Text-Based Inputs

​Number Inputs

​Date and Time

​Selection

​File

​Other

​Security Notes

​Related Components

Build docs developers (and LLMs) love

Basic Usage

Handling Form Data

Top-Level Properties

Field Properties

Text Input Properties

Number Input Properties

Textarea Properties

Select Properties

Checkbox and Radio Properties

File Upload Properties

Examples

Basic Registration Form

Multi-Column Layout

Select Dropdown from Database

Radio Buttons

Toggle Switches

File Upload

Auto-Submit on Change

Form with External Submit Buttons

Input with Prefix and Suffix

Form with Headers

Hidden Fields

All Input Types

Text-Based Inputs

Number Inputs

Date and Time

Selection

File

Other

Security Notes

Related Components