# Button

> A Button widget for triggering actions within a form

Button widgets are [Interactive Fields](https://golemui.com/dx/widgets-reference/interactive-fields/overview.md) (Actions) used to trigger events, submit forms, or perform custom logic defined in the form configuration.


```ts title="button.ts"

export default [
  gui.actions.button({
    label: 'Click Me',
    uid: 'button_basic',
  }),
];
```

_Live demo on the docs page. Form definition: [button.ts](https://golemui.com/template/widgets-dx/button/button.ts)._

## Props

Use these `props` to customize your Button widget.

| prop           | type                               | description                                                                                                      |
| -------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `actionType`   | `'button' \| 'submit'`             | **Optional**. Sets the HTML button type. `'submit'` triggers form-wide validation on click (Default: `'button'`) |
| `ariaLabel`    | string                             | The button's accessible name when it has no `label`, such as an icon-only button. Accepts a translation config   |
| `disabled`     | boolean                            | Whether the button is interactive or not                                                                         |
| `icon`         | string                             | Optional CSS class for an icon (Implementation may vary by framework)                                            |
| `iconPosition` | `'left' \| 'right'`                | **Optional**. Position of the icon relative to the label (Default: `left`)                                       |
| `label`        | string                             | The text displayed inside the button (Optional if icon is present)                                               |
| `variant`      | `'filled' \| 'outlined' \| 'link'` | **Optional**. Button style variant (Default: `filled`)                                                           |

### Variants

Buttons support three style variants: `filled` (default), `outlined`, and `link`.

#### Outlined


```ts

export default [
  gui.actions.button({
    variant: 'outlined',
    label: 'Click Me',
    uid: 'button_outlined',
  }),
];
```

_Live demo on the docs page. Form definition: [button-outlined.ts](https://golemui.com/template/widgets-dx/button/button-outlined.ts)._

#### Link


```ts

export default [
  gui.actions.button({
    variant: 'link',
    label: 'Click Me',
    uid: 'button_link',
  }),
];
```

_Live demo on the docs page. Form definition: [button-link.ts](https://golemui.com/template/widgets-dx/button/button-link.ts)._

### Icons

Buttons support icons that can be positioned to the left or right of the label. The label itself is optional if an icon is provided.

#### Button with Icon (Left)


```ts

export default [
  gui.actions.button({
    icon: 'save',
    label: 'Save',
  }),
];
```

_Live demo on the docs page. Form definition: [button-icon.ts](https://golemui.com/template/widgets-dx/button/button-icon.ts)._

#### Button with Icon (Right)


```ts

export default [
  gui.actions.button({
    icon: 'save',
    iconPosition: 'right',
    label: 'Save',
  }),
];
```

_Live demo on the docs page. Form definition: [button-icon-right.ts](https://golemui.com/template/widgets-dx/button/button-icon-right.ts)._

#### Icon Only Button

<Aside>An icon-only button must set `ariaLabel`, its name for screen readers. With a `label`, the label is the name and `ariaLabel` is ignored.</Aside>


```ts

export default [
  gui.actions.button({
    icon: 'save',
    ariaLabel: 'Save',
  }),
];
```

_Live demo on the docs page. Form definition: [button-icon-only.ts](https://golemui.com/template/widgets-dx/button/button-icon-only.ts)._

### Disabled State

You can disable the button by setting the `disabled` property to `true`.


```ts title="button.ts"

export default [
  gui.actions.button({
    label: 'Click Me',
    disabled: true,
    uid: 'button_disabled',
  }),
];
```

_Live demo on the docs page. Form definition: [button-disabled.ts](https://golemui.com/template/widgets-dx/button/button-disabled.ts)._

## Submit behavior

Setting `actionType: 'submit'` turns the button into a form submission trigger. Clicking it runs form-wide validation before emitting the `formSubmit` event. If any field fails validation, submission is blocked.

### Validation feedback

When a submit attempt fails due to validation errors, the button automatically displays an error border. This gives users a visual cue even when the invalid fields are not visible — for example in a long form or in a tab that is not currently selected.

The error border clears automatically once all validation errors are resolved.

This behavior is on by default and requires no additional configuration. In the demo below, submitting with the required Email field empty flags the button with an error border:


```ts title="button.ts"

export default [
  gui.inputs.textInput('email', {
    label: 'Email',
    validator: {
      required: true,
    },
    uid: 'email',
  }),
  gui.actions.button({
    label: 'Submit',
    uid: 'submit-button',
    actionType: 'submit',
  }),
];
```

_Live demo on the docs page. Form definition: [button-submit.ts](https://golemui.com/template/widgets-dx/button/button-submit.ts)._

If you prefer to block submission entirely rather than just flagging the button, you can combine `actionType: 'submit'` with the `$formIsInvalid` expression variable:

```json
{
  "uid": "submit-button",
  "kind": "action",
  "type": "button",
  "label": "Submit",
  "actionType": "submit",
  "disabled": { "when": "$formIsInvalid" }
}
```

Validation never runs at mount, so `$formIsInvalid` starts as `false` and the button above is enabled on a pristine form; it disables only after the first validated interaction. To keep it disabled until required fields hold data, add a data check: `"disabled": { "when": "$formIsInvalid || $form.email === undefined" }`. Either way, the runtime blocks the submit event itself while the form is invalid.

See [Validators](https://golemui.com/dx/features/validators.md) for how to configure field-level validation rules.

## Styling

Buttons can be styled as explained in the [Styling Guide](https://golemui.com/dx/styling/overview.md).

### CSS Variables

Following you will find a list with the CSS Variables and a quick description of what you will style.

| CSS Variable                  | Description                                                        |
| ----------------------------- | ------------------------------------------------------------------ |
| `--gui-intent-primary`        | Background color of the button                                     |
| `--gui-intent-primary-text`   | Color of the text inside the button                                |
| `--gui-intent-primary-hover`  | Background color on hover                                          |
| `--gui-intent-primary-active` | Background color when clicked                                      |
| `--gui-radius-md`             | Border radius of the button                                        |
| `--gui-intent-error`          | Border color when a submit button has unresolved validation errors |
| `--gui-shadow-focus-error`    | Focus ring color when a submit button is in the invalid state      |

### Anatomy

This is the anatomy of the Button Widget in case you want to use your CSS styles.


```html title="button-anatomy.html"
<gui-button-interactive class="gui-button gui-field">
  <gui-button class="gui-field">
    <div class="gui-widget">
      <button type="button" id="fieldUid" class="gui-button-icon-left" value="">
        <span>Click Me</span>
      </button>
    </div>
  </gui-button>
</gui-button-interactive>
```
