Button

Interactive button component that supports link navigation, page data source operations (record navigation, new record, mode switching), form submission, and custom JavaScript execution. Save/Delete actions must use a custom‑script with navigation. Two visual variants are available, and the button can be enabled or disabled dynamically based on data context.

Use Cases

• Navigation buttons linking to pages or anchor sections
• Save/Delete buttons (must use custom‑script with navigation – page‑data‑source save/delete removed)
• Record navigation buttons (Next, Previous, First, Last)
• Form submission buttons
• Custom script execution buttons for complex workflows
• Call‑to‑action buttons (Sign Up, Get Started, Contact Us)

Properties

label

Button text displayed to user. Type: string. Tip: Use action verbs, be specific, and keep the label to 2‑3 words (max 20 characters). Recommended patterns:

• action‑verbs: Use verbs such as Save, Delete, Create, Submit, Navigate, Send
• clarity: Be specific, e.g., “Save Record” instead of “Save”
• length: 2‑3 words for clear, scannable buttons

variant

Visual style variant indicating button importance/hierarchy. Type: string. Options: primary, secondary. Default: primary. Visual impact:

• primary – Solid dark background (#1e293b), white text, prominent shadow; visually dominant for main actions.
• secondary – Light gray background (#f1f5f9), dark text, subtle shadow; less prominent for alternative actions.

Tip: Use primary for main actions (Save, Submit, Get Started, Sign Up, Create); secondary for alternatives (Cancel, Go Back, Learn More, View Details). Maintain one primary button per section; multiple secondary buttons are allowed.

actionType

Type of action the button performs when clicked. Determines which additional properties are required. Type: string. Options: link, page-data-source, submit-form, custom-script. Default: link. Visual impact: Controls button behavior on click – link navigates, page-data-source performs data operations, submit-form submits forms, custom-script runs JavaScript.

actionTypeFields

Container object for action‑specific configuration. Properties vary based on actionType. Type: object.

• href (string) – Link destination for actionType='link'. Can be an anchor, relative path, or external URL.
• targetDataSource (string) – Page data source ID for actionType='page-data-source'. Must reference a configured data source.
• pageDataSourceAction (string) – Data operation for actionType='page-data-source'. Options: navigate-next, navigate-previous, navigate-first, navigate-last, new-record, enter-edit-mode, enter-view-mode. Visual impact describes each operation (e.g., navigate-next loads next record and auto‑disables when none). Tip: Use navigate‑next/previous for browsing, custom‑script for save/delete, and enter‑edit‑mode/enter‑view‑mode for mode switching.
• confirmMessage (string) – Confirmation dialog for destructive actions (delete‑record). Default: “Are you sure you want to delete this record?”.
• customScript (string) – JavaScript code for actionType='custom-script'. Runs in a restricted sandbox; use context.[dataSourceId].getField() and .setField() APIs. Security note: No access to window, document, fetch, eval, or Function.

linkFields

Configuration for actionType='link'. Type: object.

• targetPage (string) – Internal page slug to navigate to.
• href (string) – External URL or anchor; targetPage takes priority.
• queryParams (object) – Key‑value pairs appended as URL query parameters. Supports {{expression}} syntax for dynamic values. Tip: Use for cross‑page forms to pass record IDs and auto‑populate target fields; never create visible inputs for foreign key IDs.

customCss

Custom CSS styles for advanced styling. Parsed as CSS property‑value pairs. Type: string. Security note: Parsed by a CSS parser with tenant‑level isolation.

Best Practices

• CRITICAL: For SAVE/DELETE operations, use actionType='custom-script' with navigation – page‑data‑source save-record and delete-record have been removed.
• Always specify actionType based on button purpose (link, page-data-source, submit-form, or custom-script).
• All buttons should have smooth hover effects – use customCss for enhanced interactivity.
• Primary CTAs can use subtle pulse animations for emphasis (celebrations only – NOT for business apps).
• Use customCss for hover states: transition: transform 0.3s ease, box-shadow 0.3s ease; &:hover { transform: translateY(-2px); box-shadow: 0 8px 16px rgba(0,0,0,0.2); }
• Use actionType='link' for simple navigation (pages, anchors, external URLs).
• Use actionType='page-data-source' ONLY for: navigate-next, navigate-previous, navigate-first, navigate-last, new-record, enter-edit-mode, enter-view-mode.
• Use actionType='submit-form' for form submission buttons.
• Use actionType='custom-script' for save/delete operations (MANDATORY!) and complex workflows.
• Use variant='primary' for main actions (Save, Submit, Get Started).
• Use variant='secondary' for alternative actions (Cancel, Go Back, Learn More).
• Set confirmMessage for destructive actions (delete-record) to prevent accidental data loss.
• Keep button labels action‑oriented (2‑3 words: “Save Record”, “Next”, “Sign Up”).
• When using page-data-source actions, ALWAYS specify targetDataSource ID.

Common Mistakes

🚨 CRITICAL: Using actionType='page-data-source' with pageDataSourceAction='save-record' or 'delete-record'

Why it's a problem: These actions have been permanently removed. The button will not work, and save/delete operations must use actionType='custom-script' with navigation back to the list page.

Fix: ALWAYS use actionType='custom-script' for save/delete operations.

CRITICAL: Using context.pageData or context.setPageData() – these APIs DO NOT EXIST

Why it's a problem: The correct API is context.[dataSourceId].getField() and context.[dataSourceId].setField(). Using the non‑existent APIs causes a runtime error.

Fix: ALWAYS use context.[dataSourceId] API (NOT context.pageData or context.setPageData).

CRITICAL: Using actionTypeFields.script instead of actionTypeFields.customScript for custom‑script buttons

Why it's a problem: The field name is customScript, not script. Using the wrong name prevents the code from displaying or executing.

Fix: ALWAYS use actionTypeFields.customScript (NOT actionTypeFields.script) for custom script code.

Using actionType='page-data-source' without setting targetDataSource

Why it's a problem: The button does not know which data source to operate on, so the click does nothing.

Fix: Set actionTypeFields.targetDataSource to the appropriate page data source ID (e.g., customerDetails).

Not setting confirmMessage for delete-record actions

Why it's a problem: Users can accidentally delete records with one click, leading to permanent data loss.

Fix: Always set actionTypeFields.confirmMessage for delete‑record actions (e.g., “Are you sure you want to delete this customer?”).

Using async operations in custom scripts without await

Why it's a problem: Operations like save(), delete(), navigateNext() are asynchronous. Without await, the script continues before completion, causing race conditions.

Fix: Always use await for async operations (e.g., await context.customerDetails.save()).

Trying to use window, document, or fetch in custom scripts

Why it's a problem: Custom scripts run in a restricted sandbox; these APIs are blocked to prevent XSS attacks.

Fix: Use only the provided context API (e.g., context.alert(), data source methods).

Creating a visible Input for foreign key IDs on form pages instead of using queryParams + defaultValues

Why it's a problem: Users should never manually type a UUID. Record IDs should be passed automatically via queryParams and auto‑populated on the target page.

Fix: Use linkFields.queryParams on the source button together with defaultValues on the target page’s query.

Generic button labels like “Click Here”, “Submit”, “Go”

Why it's a problem: Non‑descriptive labels don’t communicate the button’s purpose, causing user hesitation.

Fix: Use specific, action‑oriented labels such as “Save Customer”, “Delete Order”, “Next Record”, “Create New”.

Using variant='primary' for all buttons

Why it's a problem: When every button looks important, none stand out, and users can’t identify the primary action.

Fix: Use variant='primary' for ONE main action per section and variant='secondary' for alternatives.

Not considering auto‑disable states for page-data-source buttons

Why it's a problem: Buttons like “Next” should auto‑disable when no next record exists; manual disable logic is unnecessary.

Fix: Trust the automatic disable logic (e.g., navigate‑next disables when canNavigateNext is false).