# Adaptable Buttons

Canonical page: https://www.adaptabletools.com/docs/ui-tutorial-displaying-adaptable-buttons

- Adaptable Buttons are widely used in AdapTable and are highly configurable and flexible
- Buttons can appear standalone in AdapTable (e.g in the Dashboard, ToolPanel or Action Columns)
- Buttons can also appear in an Adaptable Form (e.g. when using Alerts, Custom Export Destinations or DataSets)

## Topics on this Page

| Topic                                         | Summary                     |
| --------------------------------------------- | --------------------------- |
| [Button properties](#button-properties)       | `AdaptableButton` fields    |
| [Where buttons appear](#where-buttons-appear) | Dashboard, forms, exports   |
| [Button contexts](#button-contexts)           | Handler context per surface |

Pairs with [Adaptable Forms](https://www.adaptabletools.com/docs/ui-tutorial-configuring-adaptable-forms/index.md) · [UI Guides](https://www.adaptabletools.com/docs/ui-tutorial-overview/index.md).

An AdapTable Button is designed to be extremely configurable and styleable.

It contains many optional properties which can be provided as required.

The properties that use a function always receive the same 2 parameters when invoked (and returns an appropriate value):

- the button itself (with a generic [ButtonContext](#button-contexts))
- an appropriate [ButtonContext](#button-contexts) (matching the one of the Button)

## Button Properties

The [`Adaptable Button`](https://www.adaptabletools.com/docs/reference/adaptablebutton.md) has a number of properties and is defined as follows:

| Property | Type | Description | Default |
| --- | --- | --- | --- |
| [buttonStyle](https://www.adaptabletools.com/docs/reference/adaptablebutton.md#buttonstyle) | [`ButtonStyle`](https://www.adaptabletools.com/docs/reference/buttonstyle.md)` \| ((button: `[`AdaptableButton`](https://www.adaptabletools.com/docs/reference/adaptablebutton.md)`<CONTEXT_TYPE>, context: CONTEXT_TYPE) => `[`ButtonStyle`](https://www.adaptabletools.com/docs/reference/buttonstyle.md)`)` | Style for Button - can be object or function that provides a `ButtonStyle` object |   |
| [disabled](https://www.adaptabletools.com/docs/reference/adaptablebutton.md#disabled) | `(button: `[`AdaptableButton`](https://www.adaptabletools.com/docs/reference/adaptablebutton.md)`<CONTEXT_TYPE>, context: CONTEXT_TYPE) => boolean` | Function that disables / enables the button based on its evaluation result |   |
| [hidden](https://www.adaptabletools.com/docs/reference/adaptablebutton.md#hidden) | `(button: `[`AdaptableButton`](https://www.adaptabletools.com/docs/reference/adaptablebutton.md)`<CONTEXT_TYPE>, context: CONTEXT_TYPE) => boolean` | Function which sets whether Button is hidden |   |
| [icon](https://www.adaptabletools.com/docs/reference/adaptablebutton.md#icon) | [`AdaptableIcon`](https://www.adaptabletools.com/docs/reference/adaptableicon.md)` \| ((button: `[`AdaptableButton`](https://www.adaptabletools.com/docs/reference/adaptablebutton.md)`<CONTEXT_TYPE>, context: CONTEXT_TYPE) => `[`AdaptableIcon`](https://www.adaptabletools.com/docs/reference/adaptableicon.md)`)` | Icon for Button - can be object or function that provides a `AdaptableIcon` object |   |
| [iconPosition](https://www.adaptabletools.com/docs/reference/adaptablebutton.md#iconposition) | `'start' \| 'end'` | Where the icon appears relative to the label | &#39;start&#39; |
| [label](https://www.adaptabletools.com/docs/reference/adaptablebutton.md#label) | `string \| ((button: `[`AdaptableButton`](https://www.adaptabletools.com/docs/reference/adaptablebutton.md)`<CONTEXT_TYPE>, context: CONTEXT_TYPE) => string)` | Label for Button - can be string or function that provides string |   |
| [onClick](https://www.adaptabletools.com/docs/reference/adaptablebutton.md#onclick) | `(button: `[`AdaptableButton`](https://www.adaptabletools.com/docs/reference/adaptablebutton.md)`<CONTEXT_TYPE>, context: CONTEXT_TYPE) => void` | Function to invoke when button is clicked |   |
| [tooltip](https://www.adaptabletools.com/docs/reference/adaptablebutton.md#tooltip) | `string \| ((button: `[`AdaptableButton`](https://www.adaptabletools.com/docs/reference/adaptablebutton.md)`<CONTEXT_TYPE>, context: CONTEXT_TYPE) => string)` | Tooltip for Button - can be string or function that provides string |   |

**onClick**

onClick is the function which is called when the Button is clicked and returns void:

```
onClick?: (button: AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => void;
```

Although not mandatory, this function should nearly always be provided in practice

**label**

The text to show as the Button's caption.

The property can return either a string or a function which returns a string:

```
label?: string |
  (((button: AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => string);
```

**buttonStyle**

Provides the Button Style for the Button.

The property can return either a ButtonStyle object or a function which returns a ButtonStyle:

```
buttonStyle?: ButtonStyle |
  ((button: AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => ButtonStyle);
```

**toolTip**

The text to use as the Button's Tooltip.

The property can return either a string or a function which returns a string:

```
toolTip?: string |
  ((button: AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => string);
```

**hidden**

Function that returns whether or not the Button will display.

If this property is not provided the Button will **always be displayed**

The function is invoked when the Button is about to be rendered - allowing you to decide whether it should display - and returns a boolean:

```
hidden?: (button: AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => boolean;
```

**disabled**

Function that disables / enables the button based on its evaluation result:

```
disabled?: (button: AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => boolean;
```

**icon**

The property can return either an [`AdaptableIcon`](https://www.adaptabletools.com/docs/reference/adaptableicon.md) or a function which returns an [`AdaptableIcon`](https://www.adaptabletools.com/docs/reference/adaptableicon.md):

```
icon?: AdaptableIcon | ((button: AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => AdaptableIcon);
```

See the [Guide to Adaptable Icons](https://www.adaptabletools.com/docs/ui-tutorial-creating-icon/index.md) for details on how to provide custom icons

**iconPosition**

Where the icon appears relative to the label when the button is rendered inline (Dashboard, Toolbars, Action Columns, Forms):

```
iconPosition?: 'start' | 'end';
```

| Value   | Layout                     |
| ------- | -------------------------- |
| `start` | Icon, then label (default) |
| `end`   | Label, then icon           |

- Applies to **inline** button rendering only.
- In an [Action Column Menu](https://www.adaptabletools.com/docs/handbook-action-column-menu/index.md), items use the Control's own `label` and `icon`. See the Action Columns handbook for details.

## Where buttons appear

All surfaces use the same [`Adaptable Button`](https://www.adaptabletools.com/docs/reference/adaptablebutton.md) type, rendered by a shared internal component so behaviour stays consistent.

| Surface                                                                                                               | Typical use             | Default `variant` / `tone` when `buttonStyle` omits them     |
| --------------------------------------------------------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------ |
| [Dashboard](https://www.adaptabletools.com/docs/ui-dashboard/index.md) buttons                                                          | Home / module shortcuts | `text` / `none`                                              |
| [Custom Toolbar](https://www.adaptabletools.com/docs/ui-dashboard-custom-toolbars/index.md) `toolbarButtons`                            | Toolbar actions         | `outlined` / `neutral`                                       |
| [Tool Panel](https://www.adaptabletools.com/docs/ui-tool-panel/index.md) / [Custom ToolPanel](https://www.adaptabletools.com/docs/ui-tool-panel/index.md) | Panel actions           | `text` / `none`                                              |
| [Action Column Button](https://www.adaptabletools.com/docs/handbook-action-column-button/index.md)                                      | Row actions             | `text` / `none` (set via `style`)                            |
| [Adaptable Form](https://www.adaptabletools.com/docs/handbook-alerting/index.md) footers                                                | OK / Cancel / custom    | From each button’s `buttonStyle`, or the form’s default tone |

You can always override via `buttonStyle` on the button itself.

## Serializable click handlers (Alerts)

For buttons whose **logic cannot live in JSON state** (because `onClick` is a function), use named handlers in options — the same pattern as [Alert](https://www.adaptabletools.com/docs/handbook-alerting/index.md) `commandHandlers`:

```ts
alertOptions: {
  commandHandlers: [
    {
      name: 'acknowledge',
      handler: (button, context) => { /* ... */ },
    },
  ],
},
```

Alert form buttons in state reference the handler **by name**; AdapTable resolves it at runtime. Action Column **`command`** values (`edit`, `delete`, `clone`, `create`) work the same way for row forms.

A general `handlerId` registry for Action Columns and other surfaces would follow this model; today it is fully implemented for Alerts and Action Column commands.

## Button Style

AdapTable provides a ButtonStyle object which defines how a Button will be visually rendered.

The object has 3 properties:

| Property | Type | Description | Default |
| --- | --- | --- | --- |
| [className](https://www.adaptabletools.com/docs/reference/buttonstyle.md#classname) | `string` | CSS Classname to use for the Button |   |
| [tone](https://www.adaptabletools.com/docs/reference/buttonstyle.md#tone) | `'success' \| 'error' \| 'neutral' \| 'none' \| 'warning' \| 'info' \| 'accent'` | Button&#39;s Tone - values: &#39;success&#39;, &#39;error&#39;, &#39;neutral&#39;, &#39;none&#39;, &#39;warning&#39;, &#39;info&#39;, &#39;accent&#39; | &#39;neutral&#39; |
| [variant](https://www.adaptabletools.com/docs/reference/buttonstyle.md#variant) | `'text' \| 'outlined' \| 'raised'` | How Button appears - values: &#39;text&#39;, &#39;outlined&#39;, &#39;raised&#39; | &#39;outlined&#39; |

### Understanding Button Style

**Tone**

The `tone` provides the colour for the button using the theme's [CSS Variables](https://www.adaptabletools.com/docs/handbook-theming-custom/index.md). The options are:

| Tone Value | [CSS Variables](https://www.adaptabletools.com/docs/handbook-theming-custom/index.md) |
| ---------- | ------------------------------------------------------------------- |
| success    | --ab-color-success                                                  |
| error      | --ab-color-destructive                                              |
| neutral    | --ab-color-primary-foreground                                       |
| none       | inherit                                                             |
| warning    | --ab-color-warn                                                     |
| info       | --ab-color-info                                                     |
| accent     | --ab-color-accent                                                   |

**Variant**

The `variant` property specifies how the Button will appear and has 3 options:

| Variant Value | Behaviour              |
| ------------- | ---------------------- |
| text          | Displays the caption   |
| outlined      | Provides a border      |
| raised        | Accentuates the button |

## Button Contexts

All the functions that the Button can receive, include a `Context` parameter.

Each implementation of the Adaptable Button in AdapTable will be provided with its own, bespoke, `context` property that contains information relevant to that particular use case.

In addition the `button` argument is of generic type of the same Context

```ts
button: AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE
```

There are 8 Context Types - for 8 different use cases where Adaptable Buttons are provided:

| Class                                                                              | Module                                | When Used                        | Base Class                                       |
| ---------------------------------------------------------------------------------- | ------------------------------------- | -------------------------------- | ------------------------------------------------ |
| [`ActionColumnContext`](https://www.adaptabletools.com/docs/reference/actioncolumncontext.md)                   | [Action Column](#action-column)       | In the generated buttons         | [`BaseContext`](https://www.adaptabletools.com/docs/reference/basecontext.md) |
| [`AlertFormContext`](https://www.adaptabletools.com/docs/reference/alertformcontext.md)                         | [Alert](#alert)                       | When a Notification is displayed | [`FormContext`](https://www.adaptabletools.com/docs/reference/formcontext.md) |
| [`ExportFormContext`](https://www.adaptabletools.com/docs/reference/exportformcontext.md)                       | [Export](#export)                     | In Custom Destination Forms      | [`FormContext`](https://www.adaptabletools.com/docs/reference/formcontext.md) |
| [`DashboardButtonContext`](https://www.adaptabletools.com/docs/reference/dashboardbuttoncontext.md)             | [Dashboard](#dashboard)               | In Dashboard Buttons             | [`BaseContext`](https://www.adaptabletools.com/docs/reference/basecontext.md) |
| [`CustomToolbarButtonContext`](https://www.adaptabletools.com/docs/reference/customtoolbarbuttoncontext.md)     | [Custom Toolbar](#custom-toolbar)     | Buttons in Custom Toolbars       | [`BaseContext`](https://www.adaptabletools.com/docs/reference/basecontext.md) |
| [`ToolPanelButtonContext`](https://www.adaptabletools.com/docs/reference/toolpanelbuttoncontext.md)             | [ToolPanel](#toolpanel)               | In ToolPanel Buttons             | [`BaseContext`](https://www.adaptabletools.com/docs/reference/basecontext.md) |
| [`CustomToolPanelButtonContext`](https://www.adaptabletools.com/docs/reference/customtoolpanelbuttoncontext.md) | [Custom ToolPanel](#custom-toolpanel) | Buttons in Custom ToolPanels     | [`BaseContext`](https://www.adaptabletools.com/docs/reference/basecontext.md) |
| [`DataSetFormContext`](https://www.adaptabletools.com/docs/reference/datasetformcontext.md)                     | [DataSet](#dataset)                   | When a DataSet displays a Form   | [`FormContext`](https://www.adaptabletools.com/docs/reference/formcontext.md) |

### Understanding Button Context

**Base Context**

All Context classes derive from a base class ([`BaseContext`](https://www.adaptabletools.com/docs/reference/basecontext.md)) which simply contains a reference to the [Adaptable API](https://www.adaptabletools.com/docs/technical-reference-adaptable-api/index.md), the [Adaptable Id](https://www.adaptabletools.com/docs/getting-started-adaptable-id/index.md) and the [current user](https://www.adaptabletools.com/docs/getting-started-user-name/index.md):

| Property | Type | Description |
| --- | --- | --- |
| [adaptableApi](https://www.adaptabletools.com/docs/reference/basecontext.md#adaptableapi) | [`AdaptableApi`](https://www.adaptabletools.com/docs/reference/adaptableapi.md) | Adaptable Api object |
| [adaptableContext](https://www.adaptabletools.com/docs/reference/basecontext.md#adaptablecontext) | `any` | Custom application Context provided in `AdaptableOptions.adaptableContext` |
| [adaptableId](https://www.adaptabletools.com/docs/reference/basecontext.md#adaptableid) | `string` | Id of current AdapTable instance |
| [adaptableStateKey](https://www.adaptabletools.com/docs/reference/basecontext.md#adaptablestatekey) | `string` | Current Adaptable State Key |
| [clientTimestamp](https://www.adaptabletools.com/docs/reference/basecontext.md#clienttimestamp) | `Date` | Time on user&#39;s computer |
| [userName](https://www.adaptabletools.com/docs/reference/basecontext.md#username) | `string` | Name of Current User |

**Form Context**

The Context Classes - which are used in Forms - derive from [`FormContext`](https://www.adaptabletools.com/docs/reference/formcontext.md) (which itself derives from BaseContext) and contains all the form data that was inputted by the user:

| Property | Type | Description |
| --- | --- | --- |
| [formData](https://www.adaptabletools.com/docs/reference/formcontext.md#formdata) | [`AdaptableFormData`](https://www.adaptabletools.com/docs/reference/adaptableformdata.md) | Adaptable Form Data |
| [adaptableContext](https://www.adaptabletools.com/docs/reference/formcontext.md#adaptablecontext) | `any` | Custom application Context provided in `AdaptableOptions.adaptableContext` |

**Action Column**

When using a button in an [Action Column](https://www.adaptabletools.com/docs/handbook-action-column/index.md) the handler receives an [`ActionColumnContext`](https://www.adaptabletools.com/docs/reference/actioncolumncontext.md) object which is defined as follows:

| Property | Type | Description |
| --- | --- | --- |
| [actionColumn](https://www.adaptabletools.com/docs/reference/actioncolumncontext.md#actioncolumn) | [`ActionColumn`](https://www.adaptabletools.com/docs/reference/actioncolumn.md)`<TData>` | Action Column in question |
| [control](https://www.adaptabletools.com/docs/reference/actioncolumncontext.md#control) | [`ActionColumnControl`](https://www.adaptabletools.com/docs/reference/actioncolumncontrol.md)`<TData, any>` | The Control currently being rendered / invoked |
| [data](https://www.adaptabletools.com/docs/reference/actioncolumncontext.md#data) | `TData` | The current row&#39;s data |
| [primaryKeyValue](https://www.adaptabletools.com/docs/reference/actioncolumncontext.md#primarykeyvalue) | `any` | Primary Key Value in current row |
| [rowNode](https://www.adaptabletools.com/docs/reference/actioncolumncontext.md#rownode) | `IRowNode<TData>` | Current AG Grid Row Node |
| [value](https://www.adaptabletools.com/docs/reference/actioncolumncontext.md#value) | `any` | Control&#39;s current value where applicable (e.g. `toggle`&#39;s checked state or `select`&#39;s selected value) |
| [adaptableContext](https://www.adaptabletools.com/docs/reference/actioncolumncontext.md#adaptablecontext) | `any` | Custom application Context provided in `AdaptableOptions.adaptableContext` |

**Alert**

When using a button in an [Alert](https://www.adaptabletools.com/docs/handbook-alerting/index.md) form the handler receives an [`AlertFormContext`](https://www.adaptabletools.com/docs/reference/alertformcontext.md)object which is defined as follows:

| Property | Type | Description |
| --- | --- | --- |
| [alert](https://www.adaptabletools.com/docs/reference/alertformcontext.md#alert) | [`AdaptableAlert`](https://www.adaptabletools.com/docs/reference/adaptablealert.md)`<TData>` | Alert that has been triggered |
| [adaptableContext](https://www.adaptabletools.com/docs/reference/alertformcontext.md#adaptablecontext) | `any` | Custom application Context provided in `AdaptableOptions.adaptableContext` |

**Export**

When using a button in a [Custom Destination](https://www.adaptabletools.com/docs/handbook-exporting/index.md) form the handler receives an [`ExportFormContext`](https://www.adaptabletools.com/docs/reference/exportformcontext.md) object which is defined as follows:

| Property | Type | Description |
| --- | --- | --- |
| [customDestination](https://www.adaptabletools.com/docs/reference/exportformcontext.md#customdestination) | [`CustomDestination`](https://www.adaptabletools.com/docs/reference/customdestination.md) | Custom Export destination |
| [report](https://www.adaptabletools.com/docs/reference/exportformcontext.md#report) | [`Report`](https://www.adaptabletools.com/docs/reference/report.md) | The exported report |
| [reportData](https://www.adaptabletools.com/docs/reference/exportformcontext.md#reportdata) | [`ExportResultData`](https://www.adaptabletools.com/docs/reference/exportresultdata.md) | The data in the report |
| [adaptableContext](https://www.adaptabletools.com/docs/reference/exportformcontext.md#adaptablecontext) | `any` | Custom application Context provided in `AdaptableOptions.adaptableContext` |

**Dashboard**

When showing a [Dashboard](https://www.adaptabletools.com/docs/ui-dashboard/index.md) Button the handler receives an [`DashboardButtonContext`](https://www.adaptabletools.com/docs/reference/dashboardbuttoncontext.md) object defined as follows:

| Property | Type | Description |
| --- | --- | --- |
| [dashboardState](https://www.adaptabletools.com/docs/reference/dashboardbuttoncontext.md#dashboardstate) | [`DashboardState`](https://www.adaptabletools.com/docs/reference/dashboardstate.md) | Current Dashboard State |
| [adaptableContext](https://www.adaptabletools.com/docs/reference/dashboardbuttoncontext.md#adaptablecontext) | `any` | Custom application Context provided in `AdaptableOptions.adaptableContext` |

**Custom Toolbar**

When rendering a [Custom Toolbar](https://www.adaptabletools.com/docs/ui-dashboard/index.md#tabs-and-toolbars) Button the handler receives an [`CustomToolbarButtonContext`](https://www.adaptabletools.com/docs/reference/customtoolbarbuttoncontext.md) object defined as follows:

| Property | Type | Description |
| --- | --- | --- |
| [customToolbar](https://www.adaptabletools.com/docs/reference/customtoolbarbuttoncontext.md#customtoolbar) | [`CustomToolbar`](https://www.adaptabletools.com/docs/reference/customtoolbar.md) | Custom Toolbar which hosts the Button |
| [adaptableContext](https://www.adaptabletools.com/docs/reference/customtoolbarbuttoncontext.md#adaptablecontext) | `any` | Custom application Context provided in `AdaptableOptions.adaptableContext` |

**ToolPanel**

When showing a [Tool Panel](https://www.adaptabletools.com/docs/ui-tool-panel/index.md) Button the handler receives an [`ToolPanelButtonContext`](https://www.adaptabletools.com/docs/reference/toolpanelbuttoncontext.md) object defined as follows:

| Property | Type | Description |
| --- | --- | --- |
| [toolPanelState](https://www.adaptabletools.com/docs/reference/toolpanelbuttoncontext.md#toolpanelstate) | [`ToolPanelState`](https://www.adaptabletools.com/docs/reference/toolpanelstate.md) | Current ToolPanel State |
| [adaptableContext](https://www.adaptabletools.com/docs/reference/toolpanelbuttoncontext.md#adaptablecontext) | `any` | Custom application Context provided in `AdaptableOptions.adaptableContext` |

**Custom ToolPanel**

When showing a button in a [Custom ToolPanel](https://www.adaptabletools.com/docs/ui-tool-panel/index.md) the handler receives an [`CustomToolPanelButtonContext`](https://www.adaptabletools.com/docs/reference/customtoolpanelbuttoncontext.md) object defined as follows:

| Property | Type | Description |
| --- | --- | --- |
| [customToolPanel](https://www.adaptabletools.com/docs/reference/customtoolpanelbuttoncontext.md#customtoolpanel) | [`CustomToolPanel`](https://www.adaptabletools.com/docs/reference/customtoolpanel.md) | The Custom ToolPanel which contains the button |
| [adaptableContext](https://www.adaptabletools.com/docs/reference/customtoolpanelbuttoncontext.md#adaptablecontext) | `any` | Custom application Context provided in `AdaptableOptions.adaptableContext` |

**DataSet**

When a [DataSet](https://www.adaptabletools.com/docs/handbook-data-sets/index.md) includes a Form, the buttons receive a [`DataSetFormContext`](https://www.adaptabletools.com/docs/reference/datasetformcontext.md) object defined as follows:

| Property | Type | Description |
| --- | --- | --- |
| [dataSet](https://www.adaptabletools.com/docs/reference/datasetformcontext.md#dataset) | [`DataSet`](https://www.adaptabletools.com/docs/reference/dataset.md) | The DataSet which triggered the Form |
| [adaptableContext](https://www.adaptabletools.com/docs/reference/datasetformcontext.md#adaptablecontext) | `any` | Custom application Context provided in `AdaptableOptions.adaptableContext` |

### FAQ

**Button vs Form?**
Forms contain **fields** and optional **buttons**; standalone buttons appear on Dashboard, toolbars, and action columns without a full form wrapper.

**Do buttons support icons?**
Yes — via [Adaptable Icon](https://www.adaptabletools.com/docs/ui-tutorial-creating-icon/index.md) on the `icon` property.
