Appearance
Widgets
Widgets are specialized Page Elements that provide configured functionality within a Page or Form. Use them when an application needs more than basic layout, text, media, navigation, or simple buttons.
Widgets provide an interface for capabilities such as displaying Project records, interacting with an AI Agent, collecting payments, or presenting specialized content. Some work primarily through their own configuration, while others depend on Project data, Integrations, AI Agents, or Page Flow.
Most Widgets are added through the Element Library, placed in the Page Editor, and configured through Element Settings.
Available Widgets
The Widgets documentation covers the following areas:
| Widget | Use It For |
|---|---|
| Data Table Widget | Display and interact with Project records through a configured table interface. |
| AI Agent Widget | Provide an interface for interacting with a configured AI Agent. |
| Payment Widgets | Collect payments using supported payment provider connections. |
| Display and Utility Widgets | Provide specialized display areas and utility content, such as Chart Area and Login Info. |
Video and YouTube elements are covered under Media Elements, rather than in this Widgets section.
How Widgets Differ from Basic Page Elements
Basic Page Elements provide the structure and content of an interface. Examples include Containers, Rows, Columns, Text, Images, Buttons, Menus, Tables, and Cards.
A Widget provides a more specialized experience that may combine presentation with configured application behavior.
For example:
- A basic Table arranges content in rows and columns. A Data Table Widget provides a configured, record-oriented table interface.
- A Button provides an action control. A Payment Widget provides a payment collection interface connected to a supported payment provider.
- A Text element displays content. An AI Agent Widget presents an interaction with an AI Agent configured elsewhere in the Project.
- A Card groups information visually. A Chart Area provides a designated area for chart output in a supported application workflow.
Widgets do not replace basic Page Elements. A Page will often combine both: layout elements position a Widget, while headings, explanatory text, and buttons help users understand and interact with it.
For repeated custom cards, tiles, or result layouts populated from Project data, see Data Design.
Understanding Widget Dependencies
The configuration required for a Widget depends on its purpose. Placing a Widget on a Page does not necessarily complete the setup of the capability it represents.
| Widget Area | Typical Dependency or Configuration |
|---|---|
| Data Table Widget | A data source and the Widget's record display and interaction settings. |
| AI Agent Widget | An AI Agent configured for the Project and selected for use by the Widget. |
| Payment Widgets | A supported payment provider connection configured under Integrations, along with payment-specific settings. |
| Chart Area | The supported configuration or runtime behavior that supplies chart output. |
| Login Info | The Project's authentication context and the information available about the signed-in Project User. |
These dependencies belong to different areas of the Project Editor:
- Element Settings configures the selected Widget's available options and presentation.
- Integrations manages supported external service connections, including payment provider connections.
- AI Agents manages AI Agent capabilities and their configuration.
- Page Flow coordinates supported browser-side interactions and runtime behavior.
- Database and Cloud Flow provide Project data and trusted backend processing where required.
For example, adding an AI Agent Widget does not itself create the AI Agent's Knowledge Sources. Similarly, placing a Payment Widget does not configure the payment provider account or connection.
Adding and Configuring a Widget
A typical setup workflow is:
- Open the Page or Form in the Page Editor.
- Select the layout area where the Widget should appear.
- Open the Element Library and add the appropriate Widget.
- Select the Widget and open Element Settings.
- Configure its available options and visual presentation.
- Set up or select any required Project capability, such as a data source, AI Agent, or Integration connection.
- Configure Page Flow if the Widget needs to participate in additional application logic.
- Save the changes and use Preview to test the complete interaction.
The required steps vary by Widget. For example, a Widget that displays information may need only its own configuration, while a payment workflow may require an Integration connection and application logic surrounding the payment.
Configure external connections and sensitive provider settings through their supported Project configuration areas, not through custom content placed on the Page.
Widgets and Page Flow
Page Flow defines browser-side behavior for a Page or Form. It can coordinate supported Widget operations with other Page Elements and application workflows.
Examples include:
- Retrieving data and refreshing information displayed in a supported Widget.
- Opening a Form as a modal in response to a user action.
- Coordinating a sequence of steps before or after a Widget interaction.
- Providing runtime values to a Widget when supported by its configuration.
- Updating the surrounding interface based on an interaction's result.
Page Flow is not required for every Widget. If the Widget's own settings and configured Project capabilities are sufficient, additional Page Flow logic may be unnecessary.
Use Page Flow when application behavior extends beyond the Widget's built-in configuration.
Runtime Widget Control
Some Widgets include Page Flow blocks or runtime commands for controlling them after the Page has loaded. Use these controls when the Page needs to react to user choices, selected records, calculated values, or workflow state.
Examples include:
- Refreshing a Data Table after data changes.
- Moving a Data Table to the next or previous page.
- Opening a Form as a modal from a Data Table action.
- Supplying a Custom Query to a Data Table at runtime.
- Passing Page-specific context to an AI Agent Widget.
- Supplying a dynamic amount to a Payment Widget before checkout.
Most Widget setup still belongs in Element Settings. Runtime controls are for behavior that happens while the Page is running.
When a Widget has dedicated Page Flow blocks, use those blocks first. Advanced JavaScript code can use the Client API where needed. For exact block inputs and API signatures, see the Frontend Programming Guide, including Page Flow and $io.ui.widgetCommand.
Browser-Side Behavior and Protected Operations
Page Flow executes in the user's browser. It can coordinate the interface and call permitted Project capabilities, but it is not a trusted security boundary.
When a workflow requires protected credentials, authoritative payment or transaction processing, sensitive authorization checks, or centrally enforced business rules, use the appropriate provider integration and trusted Backend capabilities such as Cloud Flow.
Likewise, displaying Login Info does not itself grant access to restricted Pages or authorize operations. Configure Page access and backend permissions independently.
For implementation details, see Page Flow for Forms and Widgets and Page Settings.
Choosing the Right Tool
| If You Need To... | Start With... |
|---|---|
| Arrange the Page's structure and responsive layout | Layout Elements |
| Add text, buttons, menus, images, or a basic visual table | Page Elements |
| Show Project records in a configured table interface | Data Table Widget |
| Render repeated custom cards, tiles, or other data-driven layouts | Data Design |
| Add an AI Agent interaction to a Page | AI Agent Widget |
| Collect a payment through a supported provider | Payment Widgets |
| Add Video or YouTube playback | Media Elements |
| Provide an area for supported chart output | Display and Utility Widgets |
| Display signed-in Project User information in navigation | Display and Utility Widgets |
| Coordinate a Widget with other Page interactions | Page Flow |
Login Info is also described under Menus and Navigation because it is commonly used in application headers and account menus.
Previewing and Testing Widgets
Test a Widget in the context of the complete Page, not only as an isolated visual element.
Check that:
- The Widget appears correctly at desktop, tablet, and mobile sizes.
- Its required data source, AI Agent, or Integration is configured and available.
- User actions produce the expected result.
- Any Page Flow interactions work with the surrounding Page and Forms.
- Loading, empty, unsuccessful, or unavailable states are handled appropriately where relevant.
- Access restrictions and backend permissions are enforced independently of the Widget's appearance.
For payment experiences, test the supported provider's test-mode flow before using a live payment connection. Preview can involve real data or connected services, so verify the environment and configuration before testing operations with external effects.
Saving and Previewing are part of development. Use the Project's publishing workflow to release changes to the published application.
Good Practices
- Choose the right component. Use basic Page Elements for ordinary content and layout; use Widgets when their specialized functionality is needed.
- Keep prerequisites clear. Configure or select the required Project data, AI Agent, or Integration connection.
- Explain the Widget's purpose. Provide clear headings, instructions, and surrounding actions where users need guidance.
- Use Page Flow selectively. Add it when a Widget needs application-specific coordination, not merely because a Widget is present.
- Keep protected processing in the appropriate Project capability. Do not treat browser-side logic or visible Widget state as authorization.
- Test the complete interaction. Preview data-backed, AI-assisted, payment, and other interactive experiences before publishing.
- Check responsive presentation. Make sure Widgets and surrounding content remain usable on smaller screens.
Common Mistakes
Avoid these patterns:
- Adding a Widget without configuring the Project capability it depends on.
- Choosing a Data Table Widget when a simple visual Table is sufficient, or using a basic Table when record-oriented Widget behavior is needed.
- Building custom Page Flow logic for behavior already supported by the Widget's configuration.
- Assuming a Chart Area produces chart data or output without the necessary supporting configuration or runtime behavior.
- Treating Login Info or hidden interface controls as an access-control mechanism.
- Embedding sensitive provider credentials in Page content or browser-side code.
- Testing only the Widget's appearance without testing its data, actions, errors, and dependent workflows.
- Saving changes and assuming they are automatically published.
Widgets are most effective when the selected component, its configuration, and its Project dependencies work together to provide a clear, reliable user experience.
Technical Reference
For exact Page Flow block inputs and Client API signatures related to widget coordination, see the Programming Guide:
Use the Programming Guide for precise block and API details; use this product guide for workflow, concepts, and authoring guidance.