Skip to main content

Button

A configurable Button component used to communicate actions that a user could take including triggering actions or events, submitting forms and more.

Import

// with @dhl-official/react-library:
import { DhlButton } from "@dhl-official/react-library"
// with @dhl-official/ui-libraries/react-library:
import { DhlButton } from "@dhl-official/ui-libraries/react-library"

Code​

<DhlButton onDhlClick={() => {}} variant="DHL_BUTTON.VARIANT.PRIMARY">Click here</DhlButton>

States​

loading replaces the button content with a spinner, marks the button as aria-busy and blocks interaction while an action is in progress. The button keeps its size, stays focusable and appends "loading" to its accessible name. Primary uses the on-filled spinner; Secondary, Tonal and Ghost use the on-surface one.

active applies the pressed treatment of the variant until it is toggled off and exposes aria-pressed="true". It is a persistent state, unlike the momentary :active pseudo-class.

Both props are ignored by the text variant.

<DhlButton loading>Save Draft</DhlButton>
<DhlButton active>Filter</DhlButton>

Interactive Demo​

Migrating from DUIL 1.0​

  • Rename onClick to clickEvent
  • Rename onKeyPress to keyPressEvent

Changelog​

v2.4.1-monorepo.8​

Breaking changes​
  • Deprecating isBlock property.
  • Add isFullWidth property - sets the button to 100% width of the parent container. Does NOT change the button to a block element.

Readme​

Properties​

PropertyAttributeDescriptionTypeDefault
activeactiveAn optional prop that keeps the pressed visual treatment of the variant applied until it is toggled off. Unlike the :active pseudo-class, this is persistent and exposed as aria-pressed. Not applied to the text variant.booleanfalse
dataAriaControlsdata-aria-controlsAn optional ariaControls prop that is used as a 'relationship attribute' which denotes which elements in a page an interactive element or set of elements has control over and affects. It's commonly used to describe a relationship between a button and the expandable region revealed by that button.stringundefined
dataAriaDescribedbydata-aria-describedbyAn optional prop used to associate the button with an element that describes it. Useful for explaining why a button is disabled.stringundefined
dataAriaExpandeddata-aria-expandedAn optional prop used for assistive technology support - used to mark expandable and collapsible regions.stringundefined
dataAriaLabeldata-aria-labelAn optional prop defining the text read by the screen reader to represent the component; use this if you need different text to be read from label.stringundefined
dataAriaLabelledbydata-aria-labelledbyAn optional ariaLabelledby prop that establishes the relationships between objects and their label(s), and its value should be one or more element IDs, which refer to elements that have the text needed for labelling. List multiple element IDs in a space delimited fashion.stringundefined
dataAriaPresseddata-aria-pressedAn optional ariaPressed prop that indicates the pressed state of a toggle button to assistive technology. Useful when buttons behave like on/off toggles.stringundefined
dataAutoFocusdata-auto-focusAn optional prop that when set, automatically sets focus on mount.booleanundefined
dataClassNamedata-class-nameAn optional class name prop for the component.stringundefined
dataIddata-idAn optional prop. Gives a valid HTML ID attribute value for the component.string`duil320-dhl-button-${getRandomString()}`
dataTestiddata-testidAn optional prop. The test id attached to the component as a data-testid attribute.stringundefined
dataTrackingdata-trackingAn optional data tracking prop for the component.stringundefined
formformAn optional prop used to associate the button within a form context. The value of the attribute must be the id attribute of a <form> element in the same document. If this attribute is not specified, the <button> element will be associated to an ancestor <form> element, if one exists. This attribute enables you to associate <button> elements to <form> elements anywhere within a document, not just as descendants of <form> elements.stringundefined
iconiconAn optional prop used to pass an icon to render by the children of the Buttonstringundefined
iconOrientationicon-orientationAn optional prop used to align an icon (if present) on either the left or right side of the component."left" | "right"DHL_BUTTON.ICON_ORIENTATION.RIGHT
iconSizeicon-sizeAn optional prop used to control the size of icons in the button"lg" | "md" | "sm" | "xl"undefined
isBlockis-block[DEPRECATED] An optional prop that sets whether the component should inherit the width of it's container.

booleanfalse
isDisabledis-disabledAn optional flag to define if the component is disabled.boolean | stringfalse
isFullWidthis-full-widthAn optional prop that sets the component to 100% width of it's parent container.booleanfalse
isRoundis-roundAn optional property used in conjunction with an icon only variant.booleanundefined
isStyledis-styledAn optional prop used to set/remove the styling of the component.booleantrue
labellabelAn optional prop to set component label.stringundefined
loadingloadingAn optional prop that replaces the button content with a spinner and blocks interaction while an action is in progress. Not applied to the text variant.booleanfalse
namenameAn optional value to be set to the element HTML name attribute. It takes any valid value that can be used for the name attribute of an HTMLInputElement.stringundefined
renderAsrender-asAn optional prop used to set the parent tag - used to ensure semantic HTML use"a" | "button"DHL_BUTTON.RENDER_AS.BUTTON
renderAsPropsrender-as-propsAn optional prop used to pass any additional props necessary for renderAs HTML tag. This is useful for passing additional props to the button element. The values set in the renderAsProps property takes priority over the values set in the stand alone properties. Setting conflicting values in the renderAsProps property and the stand alone properties, may generate unexpected results.{}{}
sizesizeAn optional size prop for the component."md" | "sm" | "xs"DHL_BUTTON.SIZE.MD
textVarianttext-variantAn optional prop used to set the text color."dark" | "light" | "primary"DHL_BUTTON.TEXT_VARIANT.PRIMARY
textWeighttext-weightAn optional prop used to set the font weight for text variant buttons. Only applies when variant is set to 'text'. Defaults to 'primary' (700)."light" | "primary"DHL_BUTTON.TEXT_WEIGHT.PRIMARY
typetypeAn optional type prop used to set the type of the button e.g. reset, submit or button"button" | "reset" | "submit"DHL_BUTTON.TYPE.BUTTON
variantvariantAn optional prop to select a component design variant."ghost" | "ghostBlack" | "outline" | "outlineBlack" | "primary" | "text" | "tonal"DHL_BUTTON.VARIANT.PRIMARY

Events​

EventDescriptionType
dhlButtonBlurEvent emitted when the component is blurred.CustomEvent<FocusEvent>
dhlClickEvent emitted when the component is clicked.CustomEvent<MouseEvent>
dhlKeyPressEvent emitted when a key is pressed while the component has focus.CustomEvent<KeyboardEvent>

Slots​

SlotDescription
"unnamed"unnamed children slot for Button text

Dependencies​

Used by​

Depends on​

Graph​

Built by DHL User Interface Library Team!