Developer mode
Opens components on the React tab by default.
Your bookmarks

ButtonPrimitive / React

A basic button that lets you customize.

To implement ButtonPrimitive component into your project you’ll need to add the import:

import ButtonPrimitive from "@kiwicom/orbit-components/lib/primitives/ButtonPrimitive";

After adding import into your project you can use it simply like:

<ButtonPrimitive>Hello!</ButtonPrimitive>

Props

Table below contains all types of the props available in ButtonPrimitive component.

Name Type Default Description
asComponent string | React.Element "button" The component used for the root node.
ariaControls string Id of the element the button controls.
ariaExpanded boolean Tells screen reader the controlled element from ariaControls is expanded.
background string The background of the ButtonPrimitive on initial state.
backgroundHover string The background of the ButtonPrimitive on hover state.
backgroundActive string The background of the ButtonPrimitive on active state.
backgroundFocus string The background of the ButtonPrimitive on focus state.
boxShadow string The box-shadow of the ButtonPrimitive on initial state.
boxShadowHover string The box-shadow of the ButtonPrimitive on hover state.
boxShadowActive string The box-shadow of the ButtonPrimitive on active state.
boxShadowFocus string The box-shadow of the ButtonPrimitive on focus state.
children React.Node The content of the ButtonPrimitive. See Functional specs.
circled boolean false If true, the ButtonPrimitive will have circular shape.
contentAlign string center The justify-content of inner container that wraps icons and the children.
contentWidth string The with of inner container that wraps the children.
dataTest string Optional prop for testing purposes.
disabled boolean false If true, the ButtonPrimitive will be disabled.
external boolean false If true, the ButtonPrimitive opens link in a new tab. See Functional specs
fontSize string The font-size of the ButtonPrimitive.
fontWeight string The font-weight of the ButtonPrimitive.
foreground string The color of the text inside ButtonPrimitive on initial state.
foregroundHover string The color of the text inside ButtonPrimitive on hover state.
foregroundFocus string The color of the text inside ButtonPrimitive on active state.
foregroundActive string The color of the text inside ButtonPrimitive on focus state.
fullWidth boolean false If true, the ButtonPrimitive will grow up to the full width of its container.
height string The height of the ButtonPrimitive.
href string The URL of the link to open when ButtonPrimitive is clicked. See Functional specs
iconLeft React.Node The displayed icon on the left.
iconRight React.Node The displayed icon on the right.
icons Icons Object property for passing down settings for icons inside the ButtonPrimitive.
loading boolean false If true, the loading glyph will be displayed and ButtonPrimitive will be disabled.
onClick event => void | Promise Function for handling onClick event.
padding string The inner padding of the ButtonPrimitive.
rel string Specifies the rel of an element. See Functional specs
role string Specifies the role of an element.
size enum "normal" The size of the ButtonPrimitive.
spaceAfter enum Additional margin-bottom after component. See this docs
submit boolean false If true, the ButtonPrimitive will have type="submit" attribute, otherwise type="button".
title string Adds aria-label.
tabIndex string | number "0" Specifies the tab order of an element.
width string The width of the ButtonPrimitive. Can be any string – 100px, 20%.

enum

size
"small"
"normal"
"large"

Icons

icons is special object property of ButtonPrimitive where you can pass settings that belongs to icons that is possible to use inside this component.

Name Type Description
width string The width of icons inside the ButtonPrimitive.
height string The height of icons inside the ButtonPrimitive.
leftMargin string The margin of the left icon inside the ButtonPrimitive.
rightMargin string The margin of the left icon inside the ButtonPrimitive.
foreground string The color of the icon inside the ButtonPrimitive.
foregroundHover string The color of the icon inside the ButtonPrimitive.
foregroundActive string The color of the icon inside the ButtonPrimitive.

Functional specs

  • When the external is specified, noopener and noreferrer values will automatically added to attribute rel for security reason.
  • By passing the href prop into Button, it will render into a element. If you pass asComponent prop it will override this logic.
  • If you want to render Icon only ButtonPrimitive, you just need to let children prop empty and set up any icon you want to use.
  • If you want to use the asComponent prop then YourComponent should accept at least className. Otherwise it won’t be rendered with proper styling, e.g.:
  const YourComponent = props => <div {...props} />

  <ButtonPrimitive asComponent={YourComponent}>Title</ButtonPrimitive>

If you specify the children of YourComponent component, it will override the children prop of ButtonPrimitive component, e.g.:

  const YourComponent = props => <div {...props}>YourComponent</div>;

Accessibility

A button is mainly used for indicating an action, submitting a data, opening a modal etc. If you want to use ButtonPrimitive for navigation consider using a <TextLink> for that.

  • Use ariaControls prop to add aria-controls attribute to establish the relationship between button and element which is controlled by it. aria-controls works only with a unique id of an element.

  • Use ariaExpands prop to add aria-expands to indicate screenreaders, that element controlled by button through ariaControls is expanded or not.

  • Use disabled prop to indicate users that button is inactive and they can’t interact with it.

  • Use role and tabIndex when you are rendering Button to non-actionable HTML element as div or span. However, this should be done only in edge-cases as it is anti-pattern behavior.

  • Use title to add aria-label when you need to add extra information to screen readers or there is no children presented to be used as label.