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

Behaviors

This component supports the following behaviors:

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:

<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>

<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>

<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>

<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:

<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>

<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>

<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:

size

default: "sm"

Sets the size of the button.

Available values:

<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>

<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:

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

<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:

variant

default: "solid"

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

Available values:

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

<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.

Signature: click(event: MouseEvent): void

• event: The mouse event object.

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

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

contextMenu

This event is triggered when the Button is right-clicked (context menu).

Signature: contextMenu(event: MouseEvent): void

• event: The mouse event object.

gotFocus

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

Signature: gotFocus(): void

<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>

<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.

Signature: lostFocus(): void

(See the example above)

Exposed Methods

This component does not expose any methods.

Parts

The component has some parts that can be styled through layout properties and theme variables separately:

• icon: The icon displayed within the button, if any.

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:

Theme Variables