# Button

## Overview

Buttons are clickable elements that are used to trigger actions. They communicate calls to action to the user and allow users to interact with pages in a variety of ways. Button labels express what action will occur when the user interacts with it.

![](/files/RQ9SbLupQ8HvWB6t4W3h)

### Widget API

{% tabs %}
{% tab title="CButton" %}

| Property     | Description                                                                                                                                                                                                                                                                                             |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| onTap        | <p>Called when the button is tapped.</p><ul><li><strong>Type:</strong> <code>VoidCallback</code></li><li><strong>Default:</strong> required</li></ul>                                                                                                                                                   |
| label        | <p>A text to display in the button.</p><ul><li><strong>Type:</strong> <code>String</code></li><li><strong>Default:</strong> required</li></ul>                                                                                                                                                          |
| enable       | <p>Whether the toggle is enabled or not.</p><ul><li><strong>Type:</strong> <code>bool</code></li><li><strong>Default:</strong> <code>true</code></li></ul>                                                                                                                                              |
| kind         | <p>The kind that the button represents. It can be <code>primary</code>, <code>secondary</code>, <code>danger</code>, <code>tertiary</code>, <code>ghost</code>.</p><ul><li><strong>Type:</strong> <code>CButtonKind</code></li><li><strong>Default:</strong> <code>CButtonKind.primary</code></li></ul> |
| size         | <p>The size of this button. It can be <code>regular</code>, <code>sm</code>, <code>md</code>.</p><ul><li><strong>Type:</strong> <code>CToggleSize</code></li><li><strong>Default:</strong> <code>CToggleSize.regular</code></li></ul>                                                                   |
| icon         | <p>An optional icon to display in the button.</p><ul><li><strong>Type:</strong> <code>Widget?</code></li><li><strong>Default:</strong> optional</li></ul>                                                                                                                                               |
| expand       | <p>Whether the button should fill the available width.</p><ul><li><strong>Type:</strong> <code>bool</code></li><li><strong>Default:</strong> <code>false</code></li></ul>                                                                                                                               |
| labelSize    | <p>The size (in logical pixels) to use when painting the label.</p><ul><li><strong>Type:</strong> <code>double</code></li><li><strong>Default:</strong> <code>14.0</code></li></ul>                                                                                                                     |
| {% endtab %} |                                                                                                                                                                                                                                                                                                         |

{% tab title="CButton.icon" %}

| Property      | Description                                                                                                                                                                                                                                                                                             |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| onTap         | <p>Called when the button is tapped.</p><ul><li><strong>Type:</strong> <code>VoidCallback</code></li><li><strong>Default:</strong> required</li></ul>                                                                                                                                                   |
| icon          | <p>An icon to display in the button.</p><ul><li><strong>Type:</strong> <code>Widget</code></li><li><strong>Default:</strong> required</li></ul>                                                                                                                                                         |
| enable        | <p>Whether the toggle is enabled or not.</p><ul><li><strong>Type:</strong> <code>bool</code></li><li><strong>Default:</strong> <code>true</code></li></ul>                                                                                                                                              |
| kind          | <p>The kind that the button represents. It can be <code>primary</code>, <code>secondary</code>, <code>danger</code>, <code>tertiary</code>, <code>ghost</code>.</p><ul><li><strong>Type:</strong> <code>CButtonKind</code></li><li><strong>Default:</strong> <code>CButtonKind.primary</code></li></ul> |
| size          | <p>The size of this button. It can be <code>regular</code>, <code>sm</code>, <code>md</code>.</p><ul><li><strong>Type:</strong> <code>CToggleSize</code></li><li><strong>Default:</strong> <code>CToggleSize.regular</code></li></ul>                                                                   |
| {% endtab %}  |                                                                                                                                                                                                                                                                                                         |
| {% endtabs %} |                                                                                                                                                                                                                                                                                                         |

### Example

```dart
CButton(
  label: 'Carbon Button',
  kind: CButtonKind.danger,
  icon: CIcon(CIcons.add, size: 16),
  size: CButtonSize.md,
  onTap: () {},
);

CButton.icon(
  kind: CButtonKind.danger,
  icon: CIcon(CIcons.add, size: 16),
  size: CButtonSize.md,
  onTap: () {},
);
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://nour-eldin-shobier.gitbook.io/carbon-flutter/widgets/todo-button.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.