> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Buttons

> Interactive button components for triggering actions and file uploads with comprehensive styling and configuration options.

Buttons are essential interactive elements that enable users to trigger actions, navigate between sections, and upload files. FlowX.AI provides two specialized button types, each optimized for specific use cases with extensive customization options.

![Button types overview](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/building-blocks/ui-designer/basic_buttons.png#center)

## Button types overview

Choose the right button type for your specific use case:

> [card] [Basic Button](#basic-button)
>
> Trigger actions like process advancement, sending notifications, or opening new content

> [card] [File Upload Button](#file-upload-button)
>
> Enable file selection with built-in validation for file types and sizes

## Basic button

Basic buttons serve as the primary interaction mechanism for users to perform actions within your application. They can trigger process flows, send notifications, navigate to different sections, or execute business logic.

### Configuration overview

> [card] Properties
>
> Labels and basic settings

> [card] Event Handlers
>
> Event handling and action types

> [card] Styling
>
> Visual appearance and icons

### Basic button properties

> [accordion] Label configuration
>
> **Purpose**: Define the text displayed on the button. A new button starts with the label "Button" and the Fill type.
>
> **Features**:
>
> * Dynamic text from process data
> * Localization support for multi-language applications
>
> **Best Practices**:
>
> * Use action-oriented language ("Submit", "Continue", "Send")
>
> * Keep labels concise but descriptive
>
> * Consider button context and user expectations
>
> * Use consistent terminology across the application
>
> > [!TIP]
> >
> > Action buttons should clearly indicate what will happen when clicked. Use verbs like "Save Changes" instead of generic terms like "OK".

> [accordion] Hide and disable conditions, platform overrides
>
> * **Hide condition**: under **Expressions**, add a condition that hides the button when it evaluates to true.
>
> - **Disable condition**: under **Expressions**, add a condition that disables the button when it evaluates to true. File upload buttons support it too.
> - **Platform overrides**: in the **Web overrides** section (and its iOS and Android counterparts), you can override the **Label** and the **Hide** expression for one platform. No other button property can be overridden per platform.

### Event handlers configuration

Define the behavior when users interact with your button:

> [tab] Event types
>
> | Event | Description | Use Cases |
> | - | - | - |
> | **On click** | Triggered when button is clicked/tapped | All button interactions |
>
> > [!NOTE]
> >
> > While **On click** is the only trigger, the action type determines what happens when the event occurs.

> [tab] Action types
>
> The action types you can pick depend on where the button is placed:
>
> * **In a process**: **Run local script**, **Node action**, **Dismiss**, **Start project**, **External**
> * **In a UI Flow**: **Run local script**, **Start process**, **Start workflow**, **External**, **Navigate to**, **Dismiss**. When a Chat component is in scope, **Conversation reply trigger** is also available.
>
> ![Event handler configuration](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/button-event-handler.png)
>
> > [!TIP]
> >
> > For detailed event handler configuration, see the [Event Handlers guide](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/event-handlers.md).

### Button styling & visual design

The **Styles** tab groups the button styling into these sections:

* **Properties**: **Type** and **Icon**
* **Sizing**: width and height behavior
* **Spacing**
* **Typography**: **Align**
* **Grid child**: shown only when the button sits in a grid layout
* **Advanced**: **Custom CSS class**
* **Theme overrides**: per-button overrides of the theme values (see below)

#### Button types

Set the button's visual style with the **Type** property, found on the **Styles** tab under **Properties**. Choose from three styles to match your design system:

> [tab] Fill
>
> **Appearance**: Solid background
>
> **Purpose**: Main call-to-action buttons
>
> **Characteristics**:
>
> * High contrast, prominent appearance
> * Usually one per screen/section
> * Draws immediate attention
>
> **Use Cases**: Submit forms, confirm actions, proceed to next step

> [tab] Ghost
>
> **Appearance**: Outlined style, transparent background with a border
>
> **Purpose**: Supporting actions that don't compete with primary content
>
> **Characteristics**:
>
> * Less prominent than Fill
> * Minimal visual weight
> * Integrates with content
>
> **Use Cases**: Cancel operations, alternative paths, optional actions

> [tab] Text
>
> **Appearance**: Text only, no background or border
>
> **Purpose**: Minimal visual impact for tertiary actions
>
> **Characteristics**:
>
> * Looks like clickable text
> * Lowest visual hierarchy
>
> **Use Cases**: Links, minor actions, text-based navigation

> [!TIP]
>
> For comprehensive CSS styling options, check our [Styling Guide](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-designer.md#styles-tab).

#### Icon integration

Enhance your buttons with meaningful icons:

> [accordion] Icon configuration
>
> On the **Styles** tab, under **Properties**, turn on **Icon**, then set:
>
> * **Icon key**: select **Set value** (or **Change**) to pick an icon from the Media Library
> * **Icon position**: **Left**, **Right** or **Center**. You can choose a position after an icon is set.
>
> The **Styles** tab has no icon color field. To change the icon color, use a theme override: in **Theme overrides**, set **Icon** under the state you want to style, for example **Default state**.
>
> > [!TIP]
> >
> > An icon color override changes the whole icon fill. Avoid it on multicolor icons to prevent visual distortion.

> [accordion] Icon positioning
>
> **Available Positions**:
>
> | Position | Description | Best For |
> | - | - | - |
> | **Left** | Icon before the label | Most common layout |
> | **Right** | Icon after the label | Directional actions |
> | **Center** | Icon centered in the button | Icon-only buttons |
>
> > [!TIP]
> >
> > For an icon-only button, set an icon with position **Center** and leave the label empty. The **Accessibility** section appears in the button settings only once the icon is centered: fill in **Accessibility label** there so screen readers can announce the action. Make sure the icon clearly communicates the action.
>
> ![Icon-only button example](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/platform-deep-dive/button_icon.png)

> [accordion] Theme overrides
>
> In **Theme overrides**, you can override the theme values for a single button:
>
> * **Common Properties**: **Border radius**, **Border width**, **Font**, and **Shadow** (Fill and Ghost types only)
> * **Default state**: **Text**, **Icon**, **Border** and **Background**. The Text type has no **Border** or **Background** items.
> * **Hover state** and **Pressed state**: web only
> * **Disabled state**: web and Android
>
> iOS offers only **Common Properties** and **Default state**.

## File upload button

File upload buttons provide a specialized interface for file selection with built-in validation and user feedback. They're essential for document submission, image uploads, and data import workflows.

### Configuration overview

File upload buttons share many properties with basic buttons but include specialized file handling features:

> [card] File Properties
>
> File type restrictions and validation

> [card] Validation
>
> Size limits and error handling

> [card] User Experience
>
> Optional overlay loader and success or error toasts

### File upload properties

> [!NOTE]
>
> **Label**, **Accepted file types**, **Invalid file message**, **Max file size (in bytes)** and **File size error message** are required. A new File Upload starts with the label "Upload" and the Ghost type.

> [accordion] Label Configuration
>
> **Purpose**: Clearly indicate the upload purpose
>
> **Examples**:
>
> * "Upload Document"
> * "Select Profile Picture"
> * "Import Data File"
> * "Attach Receipt"
>
> **Best Practices**:
>
> * Specify what type of file is expected
> * Include file requirements in the label if space allows
> * Use progressive disclosure for complex requirements

> [accordion] File type restrictions
>
> **Purpose**: Control which file types users can select, with the **Accepted file types** field
>
> **Configuration Options**:
>
> | Specification | Example | Purpose |
> | - | - | - |
> | **MIME Categories** | `audio/*`, `image/*`, `video/*` | Broad category filtering |
> | **Specific MIME Types** | `application/pdf`, `text/csv` | Exact format control |
> | **File Extensions** | `.doc`, `.docx`, `.jpg`, `.png` | User-friendly restrictions |
>
> You can also enter extensions without the dot: `png, jpg` is treated as `.png,.jpg`.
>
> **Common Combinations**:
>
> ```
> Images: image/*, .jpg, .jpeg, .png, .gif, .webp
> Documents: .pdf, .doc, .docx, .txt, .rtf
> Spreadsheets: .xls, .xlsx, .csv
> Archives: .zip, .rar, .7z
> ```
>
> > [!WARNING]
> >
> > Be specific about accepted file types to prevent user confusion and reduce invalid uploads.

> [accordion] File Size Management
>
> **Max file size (in bytes)**: Enter the limit in bytes, for example `10485760` for 10 MB. Set appropriate limits based on:
>
> * Server capacity and processing power
> * Network bandwidth considerations
> * Storage limitations
> * User experience expectations
>
> **Size Guidelines**:
>
> * **Images**: 5-10 MB for high quality
> * **Documents**: 25-50 MB for complex files
> * **Data Files**: Based on processing requirements
> * **Media Files**: 100+ MB for videos
>
> **Error Messages**: Provide clear feedback
>
> * "File size must be under 10 MB"
> * "Please compress your image and try again"
> * "Large files may take longer to process"

> [accordion] Validation & Error Handling
>
> **Invalid file message**: Custom messages for unsupported formats
>
> * Explain what formats are accepted
> * Provide guidance on file conversion
> * Link to help resources if needed
>
> **File size error message**: Clear size limit communication
>
> * Display the exact limit
> * Suggest file compression tools
> * Offer alternative upload methods for large files
>
> **Example Configuration**:
>
> ```
> Invalid Type: "Please upload PDF, DOC, or DOCX files only"
> Size Error: "File must be smaller than 25 MB. Current size: 35 MB"
> ```

### Runtime feedback

File upload buttons can show a loading overlay and success or error toasts, so users know whether the upload finished without needing a File Preview component or an image link.

> [card] Loading Overlay
>
> Optional overlay loader during file upload for both web and mobile

> [card] Toast Messages
>
> Success and error messages displayed as toasts at runtime, informing users about upload status

> [card] Dynamic Messages
>
> Display dynamic values in toast and loading messages for context-aware feedback

#### Configuration properties

The following properties are available in the File Upload button configuration panel:

| Property | Description |
| - | - |
| **Loading behavior** | Controls how the loading indicator appears (**None** or **Overlay**) |
| **Loading message** | Custom message displayed during upload (supports dynamic values) |
| **Toast notification on success** | Toggle to show success toast when upload completes |
| **Success message** | Custom success message (supports dynamic values) |
| **Toast notification on error** | Toggle to show error toast when upload fails |
| **Error message** | Custom error message (supports dynamic values) |

#### Configuring upload feedback

> [accordion] Loading behavior
>
> Configure how loading indicators appear during file uploads:
>
> | Option | Description |
> | - | - |
> | **None** | No loading overlay displayed |
> | **Overlay** | Full-screen overlay with spinner and optional loading message |
>
> **Loading Message Configuration**:
>
> * Configure custom messages using substitution tags or dynamic values
> * Works consistently across web and mobile platforms
> * When you choose **Overlay** and the message is empty, it's pre-filled with "The file is being uploaded..."
>
> **Example messages**:
>
> * "Uploading your document..."
> * `Uploading ${application.documentName}...`
> * "Please wait while we upload your file"

> [accordion] Success messages
>
> **Success Toast**: Displayed when the file upload completes successfully
>
> * **Enable**: Toggle "Toast notification on success" to show the toast. An empty message is pre-filled with "File successfully uploaded".
> * **Custom message**: Set a personalized success message with dynamic values
> * **Auto-dismiss**: In web apps, the toast closes automatically after 3 seconds and has no close button
>
> **Example messages**:
>
> * "File uploaded successfully!"
> * `${application.documentName} has been uploaded`
> * "Your document is ready for processing"

> [accordion] Error messages
>
> **Error Toast**: Displayed when the file upload fails
>
> * **Enable**: Toggle "Toast notification on error" to show the toast. An empty message is pre-filled with "There was an error with the upload".
> * **Custom message**: Set a personalized error message with dynamic values
> * **Auto-dismiss**: In web apps, the toast closes automatically after 3 seconds and has no close button
>
> **Example messages**:
>
> * "Upload failed. Please try again."
> * `Unable to upload ${application.documentName}. Check your connection.`
> * "File upload error. Please select a different file."

> [!TIP]
>
> Use substitution tags and dynamic values from your data model in loader and toast messages to give contextual feedback. The examples use `application.documentName` as a sample key; there is no built-in file name variable.

#### Theming

The loader and toast components inherit styling from your theme configuration:

> [tab] Loader Styling
>
> | Element | Theme Property |
> | - | - |
> | Background color | `general.appBackground` |
> | Loading text color | `general.generalTextColor` |
> | Loading text style | `general.textFont` |
> | Spinner tint color | `general.accentColor` |
> | Dimmed background | `rgba(0, 0, 0, 0.25)` |

> [tab] Toast Styling
>
> | Toast Type | Theme Property |
> | - | - |
> | Success toast | `Message.fill.success` |
> | Error toast | `Message.fill.error` |

#### Custom loader API (SDK)

For advanced customization, developers can provide custom loader components through the SDK. The `customLoader` object supports file upload loaders alongside existing process loaders:

```typescript theme={"dark"}
type CustomLoader = {
  startProcess?: Component,    // Loader for process start
  reloadProcess?: Component,   // Loader for process reload
  defaultUpload?: Component,   // Default loader for file uploads
  defaultAction?: Component,   // Default loader for actions
  actions?: Record<string, Component>  // Named action loaders
}
```

**Loader resolution order:**

1. If a named action loader exists (`customLoader.actions?.[actionName]`), use it
2. Otherwise, if `defaultAction` or `defaultUpload` is defined, use that
3. Fall back to the internal SDK loader

> [!NOTE]
>
> Custom loaders allow you to maintain consistent branding and UX patterns across your application while using the FlowX upload infrastructure.

### File upload example

Example configuration for an image upload button:

![File Upload component settings with accepted type image/\*, a 5 MB max size, and custom error messages](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/6.x/6.x-file-upload-settings.png)

**Configuration Details**:

* **Accepted Types**: `image/*` (all image formats)
* **Max Size**: 5 MB
* **Error Handling**: Custom messages for type and size violations
* **UI feedback**: Optional overlay loader and success or error toasts

### File upload actions

> [!NOTE]
>
> In a process, the File Upload event handler offers the **Upload** action type, plus **Run local script**. In a UI Flow, it also offers **Start process**, **Start workflow**, **External**, **Navigate to** and **Dismiss**, and **Conversation reply trigger** when a Chat component is in scope. The File Upload handles one file at a time; for multi-file uploads, see the [Multiple File Upload](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload.md) component.

> [accordion] Event configuration
>
> **Trigger**: **On click** (same as basic buttons)
>
> **Action type**: select **Upload** to upload the file the user picks.
>
> ![File Upload event handler with Action Type set to Upload](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/upload-event-handler.png)

> [accordion] Multi-file uploads
>
> The File Upload Button handles **single-file uploads** only. For batch uploads with drag-and-drop, file validation, and progress tracking, use the dedicated [Multiple File Upload](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload.md) component.

### File upload styling

File upload buttons use the same **Styles** sections (Properties, Sizing, Spacing, Typography, Grid child) and the same **Theme overrides** items as basic buttons:

> [tab] Button Types
>
> | Type | Appearance | Best Used For |
> | - | - | - |
> | **Fill** | Solid background | Primary upload actions |
> | **Ghost** | Outlined style | Secondary upload options |
> | **Text** | Text-only appearance | Subtle upload links |

> [tab] Icon and layout
>
> **Icon Integration**: Same as basic buttons
>
> * **Icon key**: Select from Media Library
> * **Icon position**: **Left**, **Right** or **Center**
> * **Icon color**: set through **Theme overrides**, not on the **Styles** tab
>
> **Recommended Icons**:
>
> * Upload arrow (↑)
> * Cloud upload (☁↑)
> * Folder or document icons
> * Plus (+) for add file actions

> [tab] Responsive Sizing
>
> | Option | Behavior | Use Case |
> | - | - | - |
> | **Fill** | Expands to container width | Full-width upload areas |
> | **Fixed** | Maintains specific width | Consistent button sizing |
> | **Auto** | Adjusts to content | Compact layouts |

## Best practices

> [card] [Accessibility](https://docs.flowx.ai/6.x/docs/platform-deep-dive/accessibility.md)
>
> * Use descriptive labels that explain the button's purpose
> * Ensure sufficient color contrast for all button states
> * For icon-only buttons (icon position **Center**), fill in the **Accessibility label** field in the button's **Accessibility** section
>
> See the [Accessibility guide](https://docs.flowx.ai/6.x/docs/platform-deep-dive/accessibility.md) for keyboard navigation, ARIA mapping, and screen reader details.

> [card] User Experience
>
> * Place primary actions prominently and consistently
> * Use loading states for actions that take time
> * Provide clear feedback for successful/failed actions
> * Group related buttons logically
> * Avoid too many competing call-to-action buttons
> * Consider touch targets for mobile users (minimum 44px)

> [card] Visual Design
>
> * Maintain consistent button styling across the application
> * Use button hierarchy to guide user attention
> * Choose icons that are universally understood
> * Test button visibility in different lighting conditions
> * Consider color-blind users when relying on color alone
> * Ensure buttons look clickable and interactive

> [card] Performance
>
> * Optimize file upload handling for large files
> * Implement proper error handling and retry mechanisms
> * Provide progress feedback for long-running actions
> * Cache frequently used icons and styling
> * Test button responsiveness under load
> * Consider offline scenarios for critical actions

## Common use cases

### Basic button scenarios

| Use case | Button type | Icon suggestion | Typical action type |
| - | - | - | - |
| **Form submission** | Fill | Checkmark | Node action (process) |
| **Cancel operation** | Ghost | Close | Dismiss |
| **Delete item** | Ghost | Trash | Node action (process) |
| **View details** | Text | Eye | Navigate to (UI Flow) |
| **Save draft** | Ghost | Save | Node action (process) |

### File upload scenarios

| Use case | Accepted file types |
| - | - |
| **Profile photo** | `image/*` |
| **Document upload** | `.pdf,.doc,.docx` |
| **Data import** | `.csv,.xlsx` |
| **Photo or video** | `image/*,video/*` |
| **Archive** | `.zip,.rar` |

## Platform considerations

> [tab] Web apps
>
> * The File Upload opens the browser file picker and accepts one file at a time
> * For drag and drop or several files, use the [Multiple File Upload](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload.md) component
> * **Hover state** and **Pressed state** theme overrides are available only on web

> [tab] Mobile apps
>
> **Mobile Optimizations**:
>
> * Touch-friendly button sizes (minimum 44px)
> * Native file picker integration
> * Camera access for image uploads
> * Simplified button layouts for smaller screens

> [tab] Cross-platform
>
> * **Label** and the **Hide** expression can be overridden per platform; other properties apply to every platform
> * **Disabled state** theme overrides apply to web and Android
> * iOS supports only the **Common Properties** and **Default state** theme overrides


## Related topics

- [Segmented button](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-component-types/form-elements/segmented-button.md)
- [Chat](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-component-types/chat.md)
- [FlowX.AI 5.1.6 Release Notes (LTS)](https://docs.flowx.ai/release-notes/v5.x/v5.1.x-lts/v5.1.6-march-2026.md)
- [Chat component](https://docs.flowx.ai/6.x/ai-platform/chat-component.md)
- [UI Flows](https://docs.flowx.ai/6.x/docs/building-blocks/ui-flows.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.