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. |
|
arialCurrent | string |
Indicates whether the element represents the current item within within a container or set of related elements. | |
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. |
foregroundFocus | 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
andnoreferrer
values will automatically added to attributerel
for security reason.
- By passing the
href
prop into Button, it will render intoa
element. If you passasComponent
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 anyicon
you want to use.
- If you want to use the
asComponent
prop then YourComponent should accept at leastclassName
. 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 addaria-controls
attribute to establish the relationship between button and element which is controlled by it.aria-controls
works only with a uniqueid
of an element. -
Use
ariaExpands
prop to addaria-expands
to indicate screenreaders, that element controlled by button throughariaControls
is expanded or not. -
Use
disabled
prop to indicate users that button is inactive and they can’t interact with it. -
Use
role
andtabIndex
when you are renderingButton
to non-actionable HTML element asdiv
orspan
. However, this should be done only in edge-cases as it is anti-pattern behavior. -
Use
title
to addaria-label
when you need to add extra information to screen readers or there is nochildren
presented to be used as label.