Button

A button is a simple component which displays a single action a user can perform on a page.

To implement Button component into your project you'll need to add the import:

import Button from "@kiwicom/orbit-components/lib/Button";

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

<Button>Hello World!</Button>

Props

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

Name	Type	Default	Description
block	`boolean`	`false`	If `true`, the Button will grow up to the full width of its container.
bordered	`boolean`	`false`	If `true`, the Button will have a lighter version, with border and light background.
circled	`boolean`	`false`	If `true`, the Button will have circular shape.
children	`React.Node`		The content of the Button. See Functional specs
component	`string \\| React.Node`	`"button"`	The component used for the root node. Either a string to use a DOM element or a component.
dataTest	`string`		Optional prop for testing purposes.
disabled	`boolean`	`false`	If `true`, the Button will be disabled.
external	`boolean`	`false`	If `true`, the Button opens link in a new tab. See Functional specs
href	`string`		The URL of the link to open when Button is clicked. See Functional specs
icon	`React.Node`		The displayed icon (will be removed in the future, use iconLeft instead).
iconLeft	`React.Node`		The displayed icon on the left.
iconRight	`React.Node`		The displayed icon on the right.
onClick	`func`		Function for handling onClick event.
size	`enum`	`"normal"`	The size of the Button.
submit	`boolean`	`false`	If `true`, the Button will have `type="submit"` attribute, otherwise `type="button"`.
type	`enum`	`"primary"`	The type of Button.
width	`number`	`0`	The width of the Button. Number is defined in `px`.

enum

type	size
`"primary"`	`"small"`
`"secondary"`	`"normal"`
`"info"`	`"large"`
`"success"`
`"warning"`
`"critical"`
`"facebook"`
`"google"`
`"white"`

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 component prop it will override this logic.
If you want to render Icon only Button, you just need to let children prop empty and set up any icon you want to use.
If you want to use the component prop then YourComponent should accept at least className. Otherwise it won't be rendered with proper styling, e.g.:
```
const YourComponent = props => <div {...props} />

<Button component={YourComponent}>Title</Button>
```
If you specify the children of YourComponent component, it will override the children prop of Button component, e.g.:
```
const YourComponent = props => <div {...props}>YourComponent</div>
```

1. General button guidelines

Identify which actions are most important. This will help to determine which button sizes to use when. Our users should be certain of what action to take next.
If you use a button in a tight space, it may be better to use full-width version. It’s also highly recommended to use full-width buttons in mobile version and mobile application.
Use actionable verbs for labels, eg. “Add passenger”, “Pay” or “Edit passenger”.
Avoid using disabled buttons. These tend to be more confusing than helpful. When you need them, always make it clear to users how to activate them.

“If everything looks important, then nothing is important.”

― Patrick Lencioni

2. Button combinations

All buttons are defined by three main properties: size, type & variation. However, we don’t use all possible button combinations; we have few defined use cases.

Basic buttons
Link buttons
Buttons with icon
Special button types (Social button, Status buttons, …)

2.1. Basic buttons

Basic buttons have three sizes (large, normal and small) and can be either primary or secondary type. With a combination of these attributes, we have six basic button types:

Use Primary Large button only for most important action on the page

Every page should have only one Primary Large button. Remaining large buttons should be secondary.

Every screen should have a maximum of one Primary Normal button

If you have more important actions on one screen, use Primary Small button to show different levels of importance.

Use secondary small buttons for additional actions on the page

The secondary small button is great for actions like „Edit passengers“ in the Manage my booking section because it stands out from the interface but doesn’t take so much attention.

Use secondary buttons for items in loop

If you have a repeated view, use the secondary button for their main action. Primary buttons would offer too many choices to select from.

Don’t use two different button sizes in one row

Don’t use any small button as a button for sending a form

Sending a form is the main action of the form, it should grab user’s attention.

💡

Use the Primary Large button instead.

Don't use two primary buttons for one form or modal

In any form or modal, there is always one primary action. Determine which one is it and for the second one

2.2. Link buttons

Link buttons have a similar look as classic links, but the area surrounding them is clickable. That makes them great to use outside of paragraphs or for less important actions in the interface. We use Link buttons only in a small and normal version.

Use Link button with an icon for additional filters in Search form

Filters are an additional feature of Search form, so it's ok to use the less prominent button.

Use Link button as standalone links, e.g., in top menu

Use negative space around the buttons, so the layout communicates that text inside that space is clickable. In this case, the icon is not needed.

Don't use Link button for any important action

They are designed not to draw attention and can be easily overlooked.

💡

Use a Primary button instead.

Don't use Link button in paragraphs

Link button have a different height than one line in a paragraph, it would break the layout.

💡

Use a Text Link instead.

2.3. Button with icon

Buttons with icon are great when you need to draw more attention to the action.

However, it’s essential to not over-use these buttons. If everything tries to grab attention, things usually get messy.

Use Button with icon when action adds another item to the page

For examples like this it's great to use some icons with 'plus' inside.

Don't use only icon button without a proper title

Icons can be understood by every user differently and it's always important to show title on hover.

2.4. Special button types

Apart from the basic types of buttons, we also have several very specific buttons. We use these buttons for specific use cases, and we usually don’t use them in all available sizes.

We use social buttons only in normal size.

Use social buttons in login form

That's their main and only function. It's recommended to use buttons together with their pre-defined labels.

Don't use a filled version of Google button

According to Google Material guidelines, we should use their with colored 'G' logo on white background.

2.4.3 Status buttons

We use status buttons exclusively in Alert messages when we need to show supporting action connected to the displayed message. We only use the small size of buttons.

Use Status button together with related Alert messages.

They are great if you need to support your message with additional action, for example, open dialog with more information.

Don't use a Status button in any other size than small

The action connected to Alert message should be only supportive, not leading.

💡

If you need more important action, try to use different component or layout.

Don't use any Status button outside of Alert message

Their colors can be confusing because all status color have some meaning behind them.

💡

Use Primary or Secondary buttons instead.

2.4.4 Destructive buttons

Destructive buttons are a specific version of critical status buttons, paired together with ‘Remove’ icon. We use them when we need to inform our users about possible dangerous actions (canceling a booking, removing an item, etc.).

Always use confirmation dialog when removing something

Be sure that users didn't click on destructive button by mistake.

It's recommended to use bordered version if using button standalone

Remove icon and color should make clear that something else is happening there. Filled button would draw unintended attention.

Use a Large Destructive button in confirmation dialog

It's also recommended to let users know that action can be irreversible and data can be lost (if that's the case). The large size of a button should also support the importance of this action.

Don't use a Destructive button without an icon

Icon helps to emphasize the importance of action. Because destructive actions are usually irreversible, we need destructive buttons to stand out.

Don't use different buttons when an action is dangerous

Destructive buttons are designed to draw more attention than normal buttons.

2.4.5 Bordered buttons

We shouldn’t use this style too much, but it needs to exist mostly because of social buttons and supporting destructive buttons.

Use Bordered button only on white background and with sufficient space around them

They can have problems with visibility and using them like this helps them to be recognizable.

Use Bordered buttons only with supporting icon

They can have problems with visibility and using them like this helps them to be recognizable.

Don't use Bordered button for secondary action

Even if they could be understandable by our users, this use would be inconsistent across our product.

💡

Use the Secondary button instead.

Don't use Bordered button on image background

They are sometimes called 'Ghost buttons'. It's because they tend to disappear when used in inappropriate cases

3. Button states

All our buttons use consistently defined set of states.

Description of behavior

Hovered – We change the background of a button to its color :hover shade. For Button Link, we use Cloud Light :hover color.
Active – We scale down the button with the $modifierScaleButtonActive design token and also change the background to its color :active shade.
Focused – The background stays same as in normal version but we create light blue shade around the button.
Disabled – We change the opacity of button with the $opacityButtonDisabled design token. It also deactivates other states like hover, active or focus.