Button

Button is the primary interactive component for triggering actions like form submissions, navigation, opening modals, and API calls. It supports multiple visual styles and sizes to match different UI contexts and importance levels.

Key features:

Visual hierarchy: Choose from solid, outlined, or ghost variants to indicate importance
Theme colors: Use primary, secondary, or attention colors for different action types
Icon support: Add icons before or after text, or create icon-only buttons
Form integration: Automatically handles form submission when used in forms

Properties

`autoFocus` (default: false)

Indicates if the button should receive focus when the page loads.

`contentPosition` (default: "center")

This optional value determines how the label and icon (or nested children) should be placedinside the Button component.

Available values:

Value	Description
`center`	Place the content in the middle (default)
`start`	Justify the content to the left (to the right if in right-to-left)
`end`	Justify the content to the right (to the left if in right-to-left)

<App>
  <Button width="200px" icon="drive" label="Button" contentPosition="center" />
  <Button width="200px" icon="drive" label="Button" contentPosition="start" />
  <Button width="200px" icon="drive" label="Button" contentPosition="end" />
  <Button width="200px" contentPosition="end">
    This is a nested text
  </Button>
</App>

Example: content position

<App>
  <Button width="200px" icon="drive" label="Button" contentPosition="center" />
  <Button width="200px" icon="drive" label="Button" contentPosition="start" />
  <Button width="200px" icon="drive" label="Button" contentPosition="end" />
  <Button width="200px" contentPosition="end">
    This is a nested text
  </Button>
</App>

`contextualLabel`

This optional value is used to provide an accessible name for the Button in the context of its usage.

`enabled` (default: true)

The value of this property indicates whether the button accepts actions (true) or does not react to them (false).

<App>
  <HStack>
    <Button label="I am enabled (by default)" />
    <Button label="I am enabled explicitly" enabled="true" />
    <Button label="I am not enabled" enabled="false" />
  </HStack>
</App>

Example: enabled

<App>
  <HStack>
    <Button label="I am enabled (by default)" />
    <Button label="I am enabled explicitly" enabled="true" />
    <Button label="I am not enabled" enabled="false" />
  </HStack>
</App>

`icon`

This string value denotes an icon name. The framework will render an icon if XMLUI recognizes the icon by its name. If no label is specified and an icon is set, the Button displays only that icon.

<App>
  <HStack>
    <Button icon="drive" label="Let there be drive" />
    <Button icon="drive" />
  </HStack>
</App>

Example: icon

<App>
  <HStack>
    <Button icon="drive" label="Let there be drive" />
    <Button icon="drive" />
  </HStack>
</App>

`iconPosition` (default: "start")

This optional string determines the location of the icon in the Button.

Available values:

Value	Description
`start`	The icon will appear at the start (left side when the left-to-right direction is set) (default)
`end`	The icon will appear at the end (right side when the left-to-right direction is set)

<App>
  <HStack>
    <Button icon="drive" label="Left" />
    <Button icon="drive" label="Right" iconPosition="right" />
  </HStack>
  <HStack>
    <Button icon="drive" label="Start" iconPosition="start" />
    <Button icon="drive" label="End" iconPosition="end" />
  </HStack>
  <HStack>
    <Button 
      icon="drive" 
      label="Start (right-to-left)" 
      iconPosition="start" 
      direction="rtl" />
    <Button 
      icon="drive" 
      label="End (right-to-left)" 
      iconPosition="end" 
      direction="rtl" />
  </HStack>
</App>

Example: icon position

<App>
  <HStack>
    <Button icon="drive" label="Left" />
    <Button icon="drive" label="Right" iconPosition="right" />
  </HStack>
  <HStack>
    <Button icon="drive" label="Start" iconPosition="start" />
    <Button icon="drive" label="End" iconPosition="end" />
  </HStack>
  <HStack>
    <Button 
      icon="drive" 
      label="Start (right-to-left)" 
      iconPosition="start" 
      direction="rtl" />
    <Button 
      icon="drive" 
      label="End (right-to-left)" 
      iconPosition="end" 
      direction="rtl" />
  </HStack>
</App>

`label`

This property is an optional string to set a label for the Button. If no label is specified and an icon is set, the Button will modify its styling to look like a small icon button. When the Button has nested children, it will display them and ignore the value of the label prop.

<App>
  <Button label="I am the button label" />
  <Button />
  <Button label="I am the button label">
    <Icon name="trash" />
    I am a text nested into Button
  </Button>
</App>

Example: label

<App>
  <Button label="I am the button label" />
  <Button />
  <Button label="I am the button label">
    <Icon name="trash" />
    I am a text nested into Button
  </Button>
</App>

`orientation` (default: "horizontal")

This property sets the main axis along which the nested components are rendered.

Available values:

Value	Description
`horizontal`	The component will fill the available space horizontally (default)
`vertical`	The component will fill the available space vertically

`size` (default: "sm")

Sets the size of the button.

Available values:

Value	Description
`xs`	Extra small
`sm`	Small (default)
`md`	Medium
`lg`	Large

<App>
  <HStack>
    <Button icon="drive" label="default" />
    <Button icon="drive" label="extra-small" size="xs" />
    <Button icon="drive" label="small" size="sm" />
    <Button icon="drive" label="medium" size="md" />
    <Button icon="drive" label="large" size="lg" />
  </HStack>
  <HStack>
    <Button label="default" />
    <Button label="extra-small" size="xs" />
    <Button label="small" size="sm" />
    <Button label="medium" size="md" />
    <Button label="large" size="lg" />
  </HStack>
</App>

Example: size

<App>
  <HStack>
    <Button icon="drive" label="default" />
    <Button icon="drive" label="extra-small" size="xs" />
    <Button icon="drive" label="small" size="sm" />
    <Button icon="drive" label="medium" size="md" />
    <Button icon="drive" label="large" size="lg" />
  </HStack>
  <HStack>
    <Button label="default" />
    <Button label="extra-small" size="xs" />
    <Button label="small" size="sm" />
    <Button label="medium" size="md" />
    <Button label="large" size="lg" />
  </HStack>
</App>

`themeColor` (default: "primary")

Sets the button color scheme defined in the application theme.

Available values:

Value	Description
`attention`	Attention state theme color
`primary`	Primary theme color (default)
`secondary`	Secondary theme color

<App>
  <HStack>
    <Button label="Button" themeColor="primary" />
    <Button label="Button" themeColor="secondary" />
    <Button label="Button" themeColor="attention" />
  </HStack>
</App>

Example: theme colors

<App>
  <HStack>
    <Button label="Button" themeColor="primary" />
    <Button label="Button" themeColor="secondary" />
    <Button label="Button" themeColor="attention" />
  </HStack>
</App>

`type` (default: "button")

This optional string describes how the Button appears in an HTML context. You rarely need to set this property explicitly.

Available values:

Value	Description
`button`	Regular behavior that only executes logic if explicitly determined. (default)
`submit`	The button submits the form data to the server. This is the default for buttons in a Form or NativeForm component.
`reset`	Resets all the controls to their initial values. Using it is ill advised for UX reasons.

`variant` (default: "solid")

The button variant determines the level of emphasis the button should possess.

Available values:

Value	Description
`solid`	A button with a border and a filled background. (default)
`outlined`	The button is displayed with a border and a transparent background.
`ghost`	A button with no border and fill. Only the label is visible; the background is colored when hovered or clicked.

<App>
  <HStack>
    <Button label="default (solid)" />
    <Button label="solid" variant="solid" />
    <Button label="outlined" variant="outlined" />
    <Button label="ghost" variant="ghost" />
  </HStack>
</App>

Example: variant

<App>
  <HStack>
    <Button label="default (solid)" />
    <Button label="solid" variant="solid" />
    <Button label="outlined" variant="outlined" />
    <Button label="ghost" variant="ghost" />
  </HStack>
</App>

Events

`click`

This event is triggered when the Button is clicked.

<App>
  <Button label="Click me!" onClick="toast('Button clicked')" />
</App>

Example: click

<App>
  <Button label="Click me!" onClick="toast('Button clicked')" />
</App>

`gotFocus`

This event is triggered when the Button has received the focus.

<App var.text="No event" >
  <HStack verticalAlignment="center" >
    <Button label="First, click me!" 
      onGotFocus="text = 'Focus received'" 
      onLostFocus="text = 'Focus lost'" />
    <Text value="Then, me!"/>
  </HStack>
  <Text value="{text}" />
</App>

Example: gotFocus

<App var.text="No event" >
  <HStack verticalAlignment="center" >
    <Button label="First, click me!" 
      onGotFocus="text = 'Focus received'" 
      onLostFocus="text = 'Focus lost'" />
    <Text value="Then, me!"/>
  </HStack>
  <Text value="{text}" />
</App>

`lostFocus`

This event is triggered when the Button has lost the focus.

(See the example above)

Exposed Methods

This component does not expose any methods.

Styling

Fixed width and height

Using a set of buttons with a fixed width or height is often helpful. So Button supports these theme variables:

width-Button
height-Button

Avoid setting the width-Button and height-Button styles in the theme definition. Instead, wrap the affected button group into a Theme component as in the following example:

Example: Buttons with fixed width

Theme Variables

Variable	Default Value (Light)	Default Value (Dark)
backgroundColor-Button--disabled	$backgroundColor--disabled	$backgroundColor--disabled
backgroundColor-Button-attention	$backgroundColor-attention	$backgroundColor-attention
backgroundColor-Button-attention--active	$color-danger-500	$color-danger-500
backgroundColor-Button-attention--hover	$color-danger-400	$color-danger-400
backgroundColor-Button-attention-ghost--active	$color-danger-100	$color-danger-100
backgroundColor-Button-attention-ghost--hover	$color-danger-50	$color-danger-50
backgroundColor-Button-attention-outlined--active	$color-danger-100	$color-danger-100
backgroundColor-Button-attention-outlined--hover	$color-danger-50	$color-danger-50
backgroundColor-Button-attention-solid	none	none
backgroundColor-Button-attention-solid--active	none	none
backgroundColor-Button-attention-solid--hover	none	none
backgroundColor-Button-primary	$color-primary-500	$color-primary-500
backgroundColor-Button-primary--active	$color-primary-500	$color-primary-500
backgroundColor-Button-primary--hover	$color-primary-400	$color-primary-400
backgroundColor-Button-primary-ghost--active	$color-primary-100	$color-primary-100
backgroundColor-Button-primary-ghost--hover	$color-primary-50	$color-primary-50
backgroundColor-Button-primary-outlined--active	$color-primary-100	$color-primary-100
backgroundColor-Button-primary-outlined--hover	$color-primary-50	$color-primary-50
backgroundColor-Button-primary-solid	none	none
backgroundColor-Button-primary-solid--active	none	none
backgroundColor-Button-primary-solid--hover	none	none
backgroundColor-Button-secondary	$color-secondary-500	$color-secondary-500
backgroundColor-Button-secondary--active	$color-secondary-500	$color-secondary-500
backgroundColor-Button-secondary--hover	$color-secondary-400	$color-secondary-400
backgroundColor-Button-secondary-ghost--active	$color-secondary-100	$color-secondary-100
backgroundColor-Button-secondary-ghost--hover	$color-secondary-100	$color-secondary-100
backgroundColor-Button-secondary-outlined--active	$color-secondary-100	$color-secondary-100
backgroundColor-Button-secondary-outlined--hover	$color-secondary-50	$color-secondary-50
backgroundColor-Button-secondary-solid	none	none
backgroundColor-Button-secondary-solid--active	none	none
backgroundColor-Button-secondary-solid--hover	none	none
borderColor-Button--disabled	$borderColor--disabled	$borderColor--disabled
borderColor-Button-attention	$color-attention	$color-attention
borderColor-Button-attention-outlined	none	none
borderColor-Button-attention-outlined--active	none	none
borderColor-Button-attention-outlined--hover	none	none
borderColor-Button-attention-solid	none	none
borderColor-Button-attention-solid--active	none	none
borderColor-Button-attention-solid--hover	none	none
borderColor-Button-primary	$color-primary-500	$color-primary-500
borderColor-Button-primary-outlined	$color-primary-600	$color-primary-600
borderColor-Button-primary-outlined--active	none	none
borderColor-Button-primary-outlined--hover	$color-primary-500	$color-primary-500
borderColor-Button-primary-solid	none	none
borderColor-Button-primary-solid--active	none	none
borderColor-Button-primary-solid--hover	none	none
borderColor-Button-secondary	$color-secondary-100	$color-secondary-100
borderColor-Button-secondary-outlined	none	none
borderColor-Button-secondary-outlined--active	none	none
borderColor-Button-secondary-outlined--hover	none	none
borderColor-Button-secondary-solid	none	none
borderColor-Button-secondary-solid--active	none	none
borderColor-Button-secondary-solid--hover	none	none
borderRadius-Button	$borderRadius	$borderRadius
borderRadius-Button-attention-ghost	none	none
borderRadius-Button-attention-outlined	none	none
borderRadius-Button-attention-solid	none	none
borderRadius-Button-primary-ghost	none	none
borderRadius-Button-primary-outlined	none	none
borderRadius-Button-primary-solid	none	none
borderRadius-Button-secondary-ghost	none	none
borderRadius-Button-secondary-outlined	none	none
borderRadius-Button-secondary-solid	none	none
borderStyle-Button	solid	solid
borderStyle-Button-attention-outlined	none	none
borderStyle-Button-attention-solid	none	none
borderStyle-Button-primary-outlined	none	none
borderStyle-Button-primary-solid	none	none
borderStyle-Button-secondary-outlined	none	none
borderStyle-Button-secondary-solid	none	none
borderWidth-Button	1px	1px
borderWidth-Button-attention-ghost	none	none
borderWidth-Button-attention-outlined	none	none
borderWidth-Button-attention-solid	none	none
borderWidth-Button-primary-ghost	none	none
borderWidth-Button-primary-outlined	none	none
borderWidth-Button-primary-solid	none	none
borderWidth-Button-secondary-ghost	none	none
borderWidth-Button-secondary-outlined	none	none
borderWidth-Button-secondary-solid	none	none
boxShadow-Button-attention-outlined	none	none
boxShadow-Button-attention-solid	none	none
boxShadow-Button-attention-solid--active	none	none
boxShadow-Button-primary-outlined	none	none
boxShadow-Button-primary-solid	none	none
boxShadow-Button-primary-solid--active	none	none
boxShadow-Button-secondary-outlined	none	none
boxShadow-Button-secondary-solid	none	none
boxShadow-Button-secondary-solid--active	none	none
fontFamily-Button-attention-ghost	none	none
fontFamily-Button-attention-outlined	none	none
fontFamily-Button-attention-solid	none	none
fontFamily-Button-primary-ghost	none	none
fontFamily-Button-primary-outlined	none	none
fontFamily-Button-primary-solid	none	none
fontFamily-Button-secondary-ghost	none	none
fontFamily-Button-secondary-outlined	none	none
fontFamily-Button-secondary-solid	none	none
fontSize-Button	$fontSize-small	$fontSize-small
fontSize-Button-attention-ghost	none	none
fontSize-Button-attention-outlined	none	none
fontSize-Button-attention-solid	none	none
fontSize-Button-primary-ghost	none	none
fontSize-Button-primary-outlined	none	none
fontSize-Button-primary-solid	none	none
fontSize-Button-secondary-ghost	none	none
fontSize-Button-secondary-outlined	none	none
fontSize-Button-secondary-solid	none	none
fontWeight-Button	$fontWeight-medium	$fontWeight-medium
fontWeight-Button-attention-ghost	none	none
fontWeight-Button-attention-outlined	none	none
fontWeight-Button-attention-solid	none	none
fontWeight-Button-primary-ghost	none	none
fontWeight-Button-primary-outlined	none	none
fontWeight-Button-primary-solid	none	none
fontWeight-Button-secondary-ghost	none	none
fontWeight-Button-secondary-outlined	none	none
fontWeight-Button-secondary-solid	none	none
height-Button	fit-content	fit-content
outlineColor-Button--focus	$outlineColor--focus	$outlineColor--focus
outlineColor-Button-attention-ghost--focus	none	none
outlineColor-Button-attention-outlined--focus	none	none
outlineColor-Button-attention-solid--focus	none	none
outlineColor-Button-primary-ghost--focus	none	none
outlineColor-Button-primary-outlined--focus	none	none
outlineColor-Button-primary-solid--focus	none	none
outlineColor-Button-secondary-ghost--focus	none	none
outlineColor-Button-secondary-outlined--focus	none	none
outlineColor-Button-secondary-solid--focus	none	none
outlineOffset-Button--focus	$outlineOffset--focus	$outlineOffset--focus
outlineOffset-Button-attention-ghost--focus	none	none
outlineOffset-Button-attention-outlined--focus	none	none
outlineOffset-Button-attention-solid--focus	none	none
outlineOffset-Button-primary-ghost--focus	none	none
outlineOffset-Button-primary-outlined--focus	none	none
outlineOffset-Button-primary-solid--focus	none	none
outlineOffset-Button-secondary-ghost--focus	none	none
outlineOffset-Button-secondary-outlined--focus	none	none
outlineOffset-Button-secondary-solid--focus	none	none
outlineStyle-Button--focus	$outlineStyle--focus	$outlineStyle--focus
outlineStyle-Button-attention-ghost--focus	none	none
outlineStyle-Button-attention-outlined--focus	none	none
outlineStyle-Button-attention-solid--focus	none	none
outlineStyle-Button-primary-ghost--focus	none	none
outlineStyle-Button-primary-outlined--focus	none	none
outlineStyle-Button-primary-solid--focus	none	none
outlineStyle-Button-secondary-ghost--focus	none	none
outlineStyle-Button-secondary-outlined--focus	none	none
outlineStyle-Button-secondary-solid--focus	none	none
outlineWidth-Button--focus	$outlineWidth--focus	$outlineWidth--focus
outlineWidth-Button-attention-ghost--focus	none	none
outlineWidth-Button-attention-outlined--focus	none	none
outlineWidth-Button-attention-solid--focus	none	none
outlineWidth-Button-primary-ghost--focus	none	none
outlineWidth-Button-primary-outlined--focus	none	none
outlineWidth-Button-primary-solid--focus	none	none
outlineWidth-Button-secondary-ghost--focus	none	none
outlineWidth-Button-secondary-outlined--focus	none	none
outlineWidth-Button-secondary-solid--focus	none	none
padding-Button	none	none
padding-Button-lg	none	none
padding-Button-md	none	none
padding-Button-sm	none	none
padding-Button-xs	none	none
paddingBottom-Button	none	none
paddingBottom-Button-lg	none	none
paddingBottom-Button-md	none	none
paddingBottom-Button-sm	none	none
paddingBottom-Button-xs	none	none
paddingHorizontal-Button	none	none
paddingHorizontal-Button-lg	$space-5	$space-5
paddingHorizontal-Button-md	$space-4	$space-4
paddingHorizontal-Button-sm	$space-4	$space-4
paddingHorizontal-Button-xs	$space-1	$space-1
paddingLeft-Button	none	none
paddingLeft-Button-lg	none	none
paddingLeft-Button-md	none	none
paddingLeft-Button-sm	none	none
paddingLeft-Button-xs	none	none
paddingRight-Button	none	none
paddingRight-Button-lg	none	none
paddingRight-Button-md	none	none
paddingRight-Button-sm	none	none
paddingRight-Button-xs	none	none
paddingTop-Button	none	none
paddingTop-Button-lg	none	none
paddingTop-Button-md	none	none
paddingTop-Button-sm	none	none
paddingTop-Button-xs	none	none
paddingVertical-Button	none	none
paddingVertical-Button-lg	$space-4	$space-4
paddingVertical-Button-md	$space-3	$space-3
paddingVertical-Button-sm	$space-2	$space-2
paddingVertical-Button-xs	$space-0_5	$space-0_5
textColor-Button	$color-surface-950	$color-surface-950
textColor-Button--disabled	$textColor--disabled	$textColor--disabled
textColor-Button-attention-ghost	none	none
textColor-Button-attention-ghost--active	none	none
textColor-Button-attention-ghost--hover	none	none
textColor-Button-attention-outlined	none	none
textColor-Button-attention-outlined--active	none	none
textColor-Button-attention-outlined--hover	none	none
textColor-Button-attention-solid	none	none
textColor-Button-attention-solid--active	none	none
textColor-Button-attention-solid--hover	none	none
textColor-Button-primary-ghost	none	none
textColor-Button-primary-ghost--active	none	none
textColor-Button-primary-ghost--hover	none	none
textColor-Button-primary-outlined	$color-primary-900	$color-primary-900
textColor-Button-primary-outlined--active	$color-primary-900	$color-primary-900
textColor-Button-primary-outlined--hover	$color-primary-950	$color-primary-950
textColor-Button-primary-solid	none	none
textColor-Button-primary-solid--active	none	none
textColor-Button-primary-solid--hover	none	none
textColor-Button-secondary-ghost	none	none
textColor-Button-secondary-ghost--active	none	none
textColor-Button-secondary-ghost--hover	none	none
textColor-Button-secondary-outlined	none	none
textColor-Button-secondary-outlined--active	none	none
textColor-Button-secondary-outlined--hover	none	none
textColor-Button-secondary-solid	none	none
textColor-Button-secondary-solid--active	none	none
textColor-Button-secondary-solid--hover	none	none
textColor-Button-solid	$const-color-surface-50	$const-color-surface-50
width-Button	fit-content	fit-content

Button

Properties

autoFocus (default: false)

contentPosition (default: "center")

contextualLabel

enabled (default: true)

icon

iconPosition (default: "start")

label

orientation (default: "horizontal")

size (default: "sm")

themeColor (default: "primary")

type (default: "button")

variant (default: "solid")

Events

click

gotFocus

lostFocus

Exposed Methods

Styling

Fixed width and height

Theme Variables

`autoFocus` (default: false)

`contentPosition` (default: "center")

`contextualLabel`

`enabled` (default: true)

`icon`

`iconPosition` (default: "start")

`label`

`orientation` (default: "horizontal")

`size` (default: "sm")

`themeColor` (default: "primary")

`type` (default: "button")

`variant` (default: "solid")

`click`

`gotFocus`

`lostFocus`