Skip to main content
The modal component creates a popup dialog box that appears over the page content. Modals are useful for displaying additional information, forms, or embedded content without navigating away from the current page.

Basic Usage

SELECT 'button' AS component;
SELECT 'Open Modal' AS title, 'my-modal' AS modal;

SELECT 'modal' AS component,
       'my-modal' AS id,
       'Modal Title' AS title;
SELECT 'This is the modal content.' AS contents;
id
text
required
Unique identifier for the modal. Used to open it from buttons or links.
title
text
required
Title displayed in the modal header
close
text
default:"close"
Text for the close button in the modal footer. Omit to hide the close button.
small
boolean
Make the modal smaller
large
boolean
Make the modal larger
scrollable
boolean
Make the modal body scrollable if content is tall
class
text
Custom CSS class for the modal
embed
url
URL whose contents will be fetched and injected into the modal. Use ?_sqlpage_embed parameter for SQLPage files.
embed_mode
text
Set to iframe to embed content in an iframe instead of fetching it
height
text
Height of the iframe when using embed_mode=iframe (e.g., “500px”)
allow
text
Permissions for iframe embeds (e.g., “camera; microphone”)
sandbox
text
Sandbox restrictions for iframe embeds
style
text
Inline CSS styles for iframe embeds

Content Properties

contents
text
Plain text content to display in the modal body
contents_md
text
Markdown-formatted content with bold, italics, links

Examples

Basic Modal

SELECT 'button' AS component;
SELECT 'Show Details' AS title,
       'details-modal' AS modal,
       'primary' AS color;

SELECT 'modal' AS component,
       'details-modal' AS id,
       'Additional Information' AS title;

SELECT 'This modal contains additional details about the selected item.' AS contents;
SELECT 'button' AS component;
SELECT 'Read More' AS title, 'info-modal' AS modal;

SELECT 'modal' AS component,
       'info-modal' AS id,
       'About Our Service' AS title,
       'Close' AS close;

SELECT '## Features

- **Fast**: Lightning-quick response times
- **Secure**: Enterprise-grade security
- **Reliable**: 99.9% uptime guarantee

Visit [our website](https://example.com) for more details.' AS contents_md;

Small Modal

SELECT 'button' AS component;
SELECT 'Confirm' AS title,
       'confirm-modal' AS modal,
       'danger' AS color;

SELECT 'modal' AS component,
       'confirm-modal' AS id,
       'Confirm Action' AS title,
       true AS small;

SELECT 'Are you sure you want to proceed?' AS contents;

Large Scrollable Modal

SELECT 'button' AS component;
SELECT 'View Terms' AS title, 'terms-modal' AS modal;

SELECT 'modal' AS component,
       'terms-modal' AS id,
       'Terms and Conditions' AS title,
       true AS large,
       true AS scrollable;

SELECT '## Terms of Service

**1. Acceptance of Terms**
By accessing and using this service, you accept and agree to be bound by the terms...

**2. Use License**
Permission is granted to temporarily access the materials...

(Additional sections would follow)' AS contents_md;
SELECT 'button' AS component;
SELECT 'View Product' AS title,
       'product-' || product_id AS modal,
       'info' AS color
FROM products
LIMIT 5;

SELECT 'modal' AS component,
       'product-' || product_id AS id,
       product_name AS title
FROM products
LIMIT 5;

SELECT '**Price:** $' || price || '

' || description AS contents_md
FROM products
LIMIT 5;
SELECT 'button' AS component;
SELECT 'Load Content' AS title, 'embed-modal' AS modal;

SELECT 'modal' AS component,
       'embed-modal' AS id,
       'Dynamic Content' AS title,
       'details.sql?_sqlpage_embed' AS embed;
SELECT 'button' AS component;
SELECT 'Watch Video' AS title, 'video-modal' AS modal;

SELECT 'modal' AS component,
       'video-modal' AS id,
       'Tutorial Video' AS title,
       true AS large,
       'https://www.youtube.com/embed/dQw4w9WgXcQ' AS embed,
       'iframe' AS embed_mode,
       '400px' AS height;
SELECT 'button' AS component;
SELECT 'Add Item' AS title,
       'add-modal' AS modal,
       'success' AS color;

SELECT 'modal' AS component,
       'add-modal' AS id,
       'Add New Item' AS title;

SELECT 'form' AS component,
       'create_item.sql' AS action;

SELECT 'name' AS name, 'Item Name' AS label, true AS required;
SELECT 'description' AS name, 'textarea' AS type;
SELECT 'Create' AS validate, 'success' AS validate_color;

Multiple Modals

SELECT 'button' AS component;
SELECT 'Info' AS title, 'info-modal' AS modal, 'info' AS color;
SELECT 'Warning' AS title, 'warning-modal' AS modal, 'warning' AS color;
SELECT 'Error' AS title, 'error-modal' AS modal, 'danger' AS color;

SELECT 'modal' AS component,
       'info-modal' AS id,
       'Information' AS title;
SELECT 'This is an informational message.' AS contents;

SELECT 'modal' AS component,
       'warning-modal' AS id,
       'Warning' AS title;
SELECT 'Please proceed with caution.' AS contents;

SELECT 'modal' AS component,
       'error-modal' AS id,
       'Error' AS title;
SELECT 'An error has occurred.' AS contents;

Confirmation Dialog

SELECT 'button' AS component;
SELECT 'Delete Item' AS title,
       'delete-modal' AS modal,
       'danger' AS color,
       'trash' AS icon;

SELECT 'modal' AS component,
       'delete-modal' AS id,
       'Confirm Deletion' AS title,
       true AS small;

SELECT 'Are you sure you want to delete this item? This action cannot be undone.' AS contents;

SELECT 'button' AS component;
SELECT 'delete.sql?id=' || :id AS link,
       'Delete' AS title,
       'danger' AS color;

Opening Modals

Modals can be opened in several ways:

From a Button

SELECT 'button' AS component;
SELECT 'Open' AS title, 'my-modal' AS modal;
SELECT 'text' AS component;
SELECT 'Click [here](#) to learn more.' AS contents_md;
-- Add data-bs-toggle="modal" data-bs-target="#my-modal" to the link in custom HTML

Programmatically with JavaScript

// In a custom JavaScript file
const modal = new bootstrap.Modal(document.getElementById('my-modal'));
modal.show();

Embedding SQLPage Content

To embed content from another SQLPage file, add the ?_sqlpage_embed parameter:
SELECT 'modal' AS component,
       'my-modal' AS id,
       'Embedded Page' AS title,
       'other-page.sql?_sqlpage_embed' AS embed;
The embedded page should not include a shell component.

Use Cases

  • Confirmation dialogs before destructive actions
  • Displaying additional details without page navigation
  • Quick forms for data entry
  • Image galleries or media viewers
  • Terms and conditions or privacy policies
  • Help text and documentation
  • Alert messages and notifications

Best Practices

  • Keep modal content focused and concise
  • Use descriptive titles
  • Don’t nest modals within modals
  • Make sure modals are accessible (keyboard navigation)
  • Use appropriate sizes (small for alerts, large for forms)
  • Provide a clear way to close the modal
  • Consider mobile users when designing modal content
  • button - Use the modal property to open modals
  • form - Display forms inside modals
  • alert - For inline alerts instead of modals

Build docs developers (and LLMs) love