---
title: Button widget
description: "Use the **Button widget** to send users to another page or to an external address. ## When to use it A Button widget performs one action: it follows a link. Use it for: - sending users to a page that…"
url: "https://auclio.com/documentation/button-widget/"
updated: "2026-08-19"
category: Widgets
---

# Button widget

Use the **Button widget** to send users to another page or to an external address.

## When to use it

A Button widget performs one action: it follows a link. Use it for:

- sending users to a page that needs no object, such as a list page;
- sending users to a page where they create something, such as a `Create new account` page;
- linking out to a system outside Auclio;
- giving a page an obvious next step.

Where users need to open a different object on every row, put the link on a Table column instead. A button is for one destination, not one per row.

## Add a Button widget

To add a Button widget:

1. Open the page and enable **Layout edit mode**.
2. Select **Add a widget**.
3. Select the **Button** tile, or drag it onto the page.
4. Enter a **Widget Title** and a **Description**.
5. Configure the button's text, appearance, and link.
6. Select **Create**.
7. Save the page layout.

## Configuration

### General Information

**Widget Title** and **Description**, each with an eye icon controlling whether it is shown.

### Button Properties

**Button Text** is the label on the button. It accepts `$(parameterName)`, so a button can read `Open $(account)`.

Selecting the icon preview opens **Select an Icon**, where you choose an icon from the library, confirm it with **Confirm**, or clear it with **Reset icon**. **Icon Position** places it **Left** or **Right** of the text.

A button needs a label or an icon: Auclio refuses to save one that has neither, reporting *Either button text or icon must be specified*.

**Button Style** sets the colour, from **Default**, **Primary**, **Secondary**, **Info**, **Success**, **Warning**, and **Error**. Use **Primary** for the main action on a page and **Default** for everything else. Reserve **Error** for destructive actions, so its meaning is not diluted.

### The link

**Link type** decides where the button goes, and offers two options.

Choose **Url** to link outside the application. Enter the address in **Url**. This field also accepts `$(parameterName)`, so a button can open a record in another system using an identifier held on the current object.

Choose **Page** to link within the application. Select the destination in **Select Page**, which lists each page with the parameters it expects beside its name.

The dialog offers no fields for supplying those parameters, so a **Page** button opens the destination without any. Where the destination needs to know which object to show, link from a Table column or a Text Grid item instead - both map **Link Parameters** - or use **Url** with an address of the form `/application/{applicationId}/page/{pageId}?account=$(account)`, since an address beginning with a slash is followed inside the application.

An icon toggle beside the link controls whether it opens in a new tab. The tooltip tells you the current state: **Open link in new tab** or **Do not open link in new tab**. Open external addresses in a new tab, and keep pages in the same tab so the browser's back button still works.

The link type cannot be changed after the widget has been created. The field is disabled while editing, with the helper text *Link type cannot be changed when editing*. If you pick the wrong one, delete the widget and add a new one.

### Control: Enable button when

The **Control** section decides whether the button is enabled. Leave it empty and the button is always enabled.

Build an expression under **Enable button when** and the button is enabled only when that expression is true, and disabled otherwise. Use it to stop users acting on an object that is not ready - for example, enabling a `Submit for approval` button only when the required fields have values.

Auclio evaluates the expression on the server, so a user cannot bypass it by editing the page in their browser.

A disabled button gives no explanation on its own. Where the reason is not obvious, put a Text widget beside it saying what has to be true first.

## Recommendations

When using Button widgets:

- label the button with the action, not the destination - `Create account`, not `Account page`;
- use one **Primary** button per page, so the main action is unambiguous;
- send users to a page that needs no object, and leave object-specific links to Table columns and Text Grid items;
- decide the link type before creating the widget, since it cannot be changed;
- test the button as a non-administrator, because the destination page has its own permissions.