---
title: Buttons
---

# Buttons

<div class="documentation__toc"></div>

## Introduction

Button `definitions` are used often in other UI definitions. For example module sections can define buttons and form actions extend them.

Understanding the anatomy and general behavior of button definitions is integral in working proficiently with UI builders.

### Defining Buttons

Buttons are defined by simple arrays. These buttons are ran through various processing and is used to `hydrate` instances of the `\Anomaly\Streams\Platform\Ui\Button\Button` class for use by the Streams Platform.

The idea behind defining buttons is that you can provide minimal information about a button and the Streams Platform can do the rest for you. Saving you from having to define the instance yourself with all required parameters.

Button definitions are simply an array:

    'buttons' => [
        'create'          => [
            'url' => '/admin/example/test/create',
            'text' => 'streams::button.create',
            'icon' => 'fa asterisk',
            'type' => 'success',
        ],
    ]

### Definition

|Key|Required|Type|Default|Description|
|--- |--- |--- |--- |--- |
|$url|false|string|{section.path}/{button.slug}/{entry.id}|The HREF attribute of the button.|
|$button|false|string|Anomaly\Streams\Platform\Ui\Button|The target button class to build.|
|$text|false|string|{vendor}.module.{module}::button.{button}.title|The button text.|
|$icon|false|string|null|A registered icon string or icon class.|
|$class|false|string|null|The CSS class to append ot the button class attribute.|
|$type|false|string|default|The button type or context. Bootstrap state colors (primary, success, etc) are supported by default.|
|$size|false|string|md|The button size. Bootstrap button sized are supported by default.|
|$attributes|false|string|null|An array of `key => value` HTML attributes. Any base level definition keys starting with `data-` will be pushed into attributes automatically.|
|$permission|false|string|null|The permission key required to display the button.|
|$disabled|false|boolean|false|Determines whether the button will be disabled or not.|
|$enabled|false|boolean|true|Determines whether the button will be rendered or not.|
|$dropdown|false|array|null|An array of item definitions. See below for more information.|
|$position|false|string|left|The position of the button's dropdown.|


## Dropdowns

The button `dropdown` property can be used to define a dropdown menu for the button.

```php
'buttons' => [
    'save' => [
        'dropdown' => [
            [
                'icon' => 'save',
                'text' => 'Save and exit',
            ],
            [
                'icon' => 'fa fa-sign-out',
                'text' => 'Save and continue',
            ]
        ]
    ]
]
```

### Definition

|Key|Required|Type|Default|Description|
|--- |--- |--- |--- |--- |
|$text|true|string|null|The text or translation key.|
|$icon|false|string|null|A registered icon string or icon class.|
|$url|true|string|null|The button URL. This gets pushed into `attributes` automatically as HREF.|
