Button

Button is an interactive element that triggers an action when clicked.

Use the Button component to trigger various actions.

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>

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>

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>

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>

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>

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>

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>  

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>

Events

click

This event is triggered when the Button is clicked.

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

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

The Button component uses these theme variables to customize its appearance:

• backgroundColor
• borderColor
• color
• fontSize
• fontWeight
• borderRadius
• borderStyle
• borderWidth
• boxShadow

Button provides are some unique behavior with styling:

Outlined and ghost buttons have no background color unless active or hovered. As ghost buttons do not have a border, setting border-related theme variables does not affect ghost buttons.

When you set a value for background-related variables, the Button component recalculates its background color tones toward the theme variable chain. Thus, using these variables may render different background colors than you expect with outlined and ghost buttons, as by default, they use background when they are active or hovered:

backgroundColor-Button-solid
backgroundColor-Button-outlined
backgroundColor-Button-ghost
backgroundColor-Button-primary-outlined
backgroundColor-Button-primary-ghost
backgroundColor-Button-secondary-outlined
backgroundColor-Button-secondary-ghost
backgroundColor-Button-attention-outlined
backgroundColor-Button-attention-ghost

The themeColor and variant properties of Button are used within theme variables as traits; first the themeColor, and then the variant value. So, when setting theme variables, you can use these traits with Button:

• Button-solid
• Button-outlined,
• Button-ghost,
• Button-primary
• Button-secondary,
• Button-attention,
• Button-primary-solid,
• Button-primary-outlined,
• Button-primary-ghost,
• Button-secondary-solid,
• Button-secondary-outlined,
• Button-secondary-ghost,
• Button-attention-solid,
• Button-attention-outlined,
• Button-attention-ghost,

The paddings of buttons can be themed through these theme variables according to the specified size (no separate theme variables for themeColor and variant):

• paddingHorizontal-xs-Button
• paddingHorizontal-sm-Button
• paddingHorizontal-md-Button
• paddingHorizontal-lg-Button
• paddingVertical-xs-Button
• paddingVertical-sm-Button
• paddingVertical-md-Button
• paddingVertical-lg-Button

The Button component handles these visual states:

• --active
• --disabled
• --focus
• --hover

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:

<App>
  <HStack>
    <Theme width-Button="120px">
      <Button label="Short" />
      <Button label="Longer" />
      <Button label="Longest" />
      <Button label="Disabled" enabled="false" />
      <Button label="Outlined" variant="outlined" />
    </Theme>
  </HStack>
</App>

Theme Variables