Skip to content

Latest commit

 

History

History
281 lines (140 loc) · 5.76 KB

button.md

File metadata and controls

281 lines (140 loc) · 5.76 KB
Raw

Button

Enables users to trigger actions in the user interface.

Properties

ariaLabel

Adds aria-label to the button element. It should be used in buttons that don't have text in order to make them accessible.

Type: String

Required: No

className

Adds the specified classes to the root element of the component.

Type: String

Required: No

disabled

Renders the button as disabled and prevents clicks.

Type: Boolean

Default: false

Valid values: true | false

Required: No

download

Specifies whether the linked URL, when selected, will prompt the user to download instead of navigate. You can specify a string value that will be suggested as the name of the downloaded file. This property only applies when an href is provided.

Type: Boolean | string

Required: No

formAction

The form action that is performed by a button click.

Type: String

Default: 'submit'

Valid values: submit | none

Required: No

href

Applies button styling to a link. Use this property if you need a link styled as a button (variant=link). For example, if you have a 'help' button that links to a documentation page.

Type: String

Required: No

iconAlign

Specifies the alignment of the icon.

Type: String

Default: 'left'

Valid values: left | right

Required: No

iconAlt

Specifies alternate text for a custom icon. We recommend that you provide this for accessibility. This property is ignored if you use a predefined icon or if you set your custom icon using the iconSvg slot.

Type: String

Required: No

iconName

Displays an icon next to the text. You can use the iconAlign property to position the icon.

Type: String

Valid values: add-plus | angle-left-double | angle-left | angle-right-double | angle-right | angle-up | angle-down | arrow-left | bug | call | calendar | caret-down-filled | caret-down | caret-left-filled | caret-right-filled | caret-up-filled | caret-up | contact | close | copy | download | edit | ellipsis | envelope | expand | external | file-open | file | filter | folder-open | folder | heart | key | lock-private | menu | microphone | notification | refresh | search | settings | share | status-in-progress | status-info | status-negative | status-pending | status-positive | status-stopped | status-warning | treeview-collapse | treeview-expand | undo | unlocked | upload | user-profile | view-full | view-horizontal | view-vertical | zoom-in | zoom-out

Required: No

iconUrl

Specifies the URL of a custom icon. Use this property if the icon you want isn't available. If you set both iconUrl and iconSvg, iconSvg will take precedence.

Type: String

Required: No

id

Adds the specified ID to the root element of the component.

Type: String

Required: No

loading

Renders the button as being in a loading state. It takes precedence over the disabled if both are set to true. It prevents users from clicking the button.

Type: Boolean

Default: false

Valid values: true | false

Required: No

target

Specifies where to open the linked URL (for example, to open in a new browser window or tab use _blank). This property only applies when an href is provided.

Type: String

Required: No

variant

Determines the general styling of the button as follows:

  • primary for primary buttons.
  • normal for secondary buttons.
  • link for tertiary buttons.
  • icon to display an icon only (no text).
  • inline-icon to display an icon-only (no text) button within a text context.

Type: String

Default: 'normal'

Valid values: normal | primary | link | icon | inline-icon

Required: No

wrapText

Specifies if the text content wraps. If you set it to false, it prevents the text from wrapping.

Type: Boolean

Default: true

Valid values: true | false

Required: No

Slots

children (text)

Text displayed in the button element.

iconSvg

Specifies the SVG of a custom icon. Use this property if you want your custom icon to inherit colors dictated by variant or hover states. When this property is set, the component will be decorated with aria-hidden="true". Ensure that the svg element:

  • has attribute focusable="false".
  • has viewBox="0 0 16 16".

If you set the svg element as the root node of the slot, the component will automatically

  • set stroke="currentColor", fill="none", and vertical-align="top".
  • set the stroke width based on the size of the icon.
  • set the width and height of the SVG element based on the size of the icon.

If you don't want these styles to be automatically set, wrap the svg element into a span. You can still set the stroke to currentColor to inherit the color of the surrounding elements.

If you set both iconUrl and iconSvg, iconSvg will take precedence.

Note: Remember to remove any additional elements (for example: defs) and related CSS classes from SVG files exported from design software. In most cases, they aren't needed, as the svg element inherits styles from the icon component.

Events

onClick

Called when the user clicks on the button and the button is not disabled or in loading state.

Detail type:

ClickDetail {
  altKey: boolean
  button: number
  ctrlKey: boolean
  metaKey: boolean
  shiftKey: boolean
}

Cancelable: Yes

onFollow

Called when the user clicks on the button with the left mouse button without pressing modifier keys (that is, CTRL, ALT, SHIFT, META), and the button has an href set.

Detail type:

Null

Cancelable: Yes

Ref functions

focus

Focuses the underlying native button.

License Summary

The documentation is made available under the Creative Commons Attribution-ShareAlike 4.0 International License. See the LICENSE file.