Intelligence Community Design System ICDS Get started Accessibility Styles Components Patterns Community
Show navigation section

Button

Guidance Code Accessibility

Component demo

Interactive example

Add to order View coffees Find out more Cancel order
<ic-buttonid='my-button'variant="primary">Add to order</ic-button>
<ic-buttonvariant="secondary">View coffees</ic-button>
<ic-buttonvariant="tertiary">Find out more</ic-button>
<ic-buttonvariant="destructive">Cancel order</ic-button>

Button details

Props

All components also accept native properties supported by the DOM, such asclassName and style .

Name Description Default
Property accept
Attribute accept

IffileUpload is set totrue , this is the accepted list of file types.

type: string - string | undefined
"*"
Property disableTooltip
Attribute disable-tooltip

Iftrue , the ic-tooltip which is shown for icon variant will be disabled. Title or aria-label must be set if this prop is not applied.

type: boolean - boolean | undefined
false
Property disabled
Attribute disabled

Iftrue , the button will be in disabled state.

type: boolean - boolean | undefined
false
Property download
Attribute download

Iftrue , the user can save the linked URL instead of navigating to it.

type: string | boolean - boolean | string | undefined
false
Property dropdown
Attribute dropdown

Iftrue , the button will show a dropdown icon.

type: boolean - boolean | undefined
false
Property dropdownExpanded
Attribute dropdown-expanded

Iftrue , the aria-expanded value will be set to true. This is only applied if the dropdown prop is also true.

type: boolean - boolean | undefined
false
Property fileInputName
Attribute file-input-name

The name of the control for the file input, which is submitted with the form data.

type: string - string | undefined
`ic-button-file-upload-input-${buttonIds++}`
Property fileUpload
Attribute file-upload

Iftrue , when the button is clicked the native file explorer will be launched.

type: boolean - boolean | undefined
false
Property form
Attribute form

The <form> element to associate the button with.

type: string - string | undefined
Property formaction
Attribute formaction

The URL that processes the information submitted by the button. It overrides the action attribute of the button's form owner. Does nothing if there is no form owner.

type: string - string | undefined
Property formenctype
Attribute formenctype

The way the submitted form data is encoded.

type: string - string | undefined
Property formmethod
Attribute formmethod

The HTTP method used to submit the form.

type: string - string | undefined
Property formnovalidate
Attribute formnovalidate

Iftrue , the form will not be validated when submitted.

type: boolean - boolean | undefined
Property formtarget
Attribute formtarget

The place to display the response from submitting the form. It overrides the target attribute of the button's form owner.

type: string - string | undefined
Property fullWidth
Attribute full-width

Iftrue , the button will fill the width of the container.

type: boolean - boolean | undefined
false
Property href
Attribute href

The URL that the link points to. This will render the button as an "a" tag.

type: string - string | undefined
Property hreflang
Attribute hreflang

The human language of the linked URL.

type: string - string | undefined
Property loading
Attribute loading

Iftrue , the button will be in loading state.

type: boolean - boolean | undefined
false
Property monochrome
Attribute monochrome

Iftrue , the button will display as monochromatic in eitherlight ordark theme.

type: boolean - boolean | undefined
false
Property multiple
Attribute multiple

IffileUpload is set totrue , this boolean determines whether multiple files are accepted.

type: boolean - boolean | undefined
false
Property referrerpolicy
Attribute referrerpolicy

How much of the referrer to send when following the link.

type: ReferrerPolicy - "" | "no-referrer" | "no-referrer-when-downgrade" | "origin" | "origin-when-cross-origin" | "same-origin" | "strict-origin" | "strict-origin-when-cross-origin" | "unsafe-url" | undefined
Property rel
Attribute rel

The relationship of the linked URL as space-separated link types.

type: string - string | undefined
Property selectedFiles

The list of the files that have been selected by a user.

type: FileList - FileList | undefined
Property size
Attribute size

The size of the button to be displayed.

type: IcSizes - "large" | "medium" | "small" | undefined
"medium"
Property target
Attribute target

The place to display the linked URL, as the name for a browsing context (a tab, window, or iframe).

type: string - string | undefined
Property theme
Attribute theme

Sets the theme color to the dark or light theme color. "inherit" will set the color based on the system settings or ic-theme component.

type: IcThemeMode - "dark" | "inherit" | "light" | undefined
"inherit"
Property tooltipPlacement
Attribute tooltip-placement

The position of the tooltip in relation to the button.

type: IcButtonTooltipPlacement - "bottom" | "left" | "right" | "top" | undefined
"bottom"
Property transparentBackground
Attribute transparent-background

Iftrue , the secondary variant of button will have a transparent background rather than white.

type: boolean - boolean | undefined
true
Property type
Attribute type

The type of the button.

type: IcButtonTypes - "button" | "reset" | "submit" | undefined
"button"
Property variant
Attribute variant

The variant of the button to be displayed.

type: IcButtonVariants - "destructive" | "icon" | "icon-destructive" | "icon-primary" | "icon-secondary" | "icon-tertiary" | "primary" | "secondary" | "tertiary" | undefined
"primary"
Property accept
Attribute accept

IffileUpload is set totrue , this is the accepted list of file types.

type: string - string | undefined
Default: "*"
Property disableTooltip
Attribute disable-tooltip

Iftrue , the ic-tooltip which is shown for icon variant will be disabled. Title or aria-label must be set if this prop is not applied.

type: boolean - boolean | undefined
Default: false
Property disabled
Attribute disabled

Iftrue , the button will be in disabled state.

type: boolean - boolean | undefined
Default: false
Property download
Attribute download

Iftrue , the user can save the linked URL instead of navigating to it.

type: string | boolean - boolean | string | undefined
Default: false
Property dropdown
Attribute dropdown

Iftrue , the button will show a dropdown icon.

type: boolean - boolean | undefined
Default: false
Property dropdownExpanded
Attribute dropdown-expanded

Iftrue , the aria-expanded value will be set to true. This is only applied if the dropdown prop is also true.

type: boolean - boolean | undefined
Default: false
Property fileInputName
Attribute file-input-name

The name of the control for the file input, which is submitted with the form data.

type: string - string | undefined
Default: `ic-button-file-upload-input-${buttonIds++}`
Property fileUpload
Attribute file-upload

Iftrue , when the button is clicked the native file explorer will be launched.

type: boolean - boolean | undefined
Default: false
Property form
Attribute form

The <form> element to associate the button with.

type: string - string | undefined
Property formaction
Attribute formaction

The URL that processes the information submitted by the button. It overrides the action attribute of the button's form owner. Does nothing if there is no form owner.

type: string - string | undefined
Property formenctype
Attribute formenctype

The way the submitted form data is encoded.

type: string - string | undefined
Property formmethod
Attribute formmethod

The HTTP method used to submit the form.

type: string - string | undefined
Property formnovalidate
Attribute formnovalidate

Iftrue , the form will not be validated when submitted.

type: boolean - boolean | undefined
Property formtarget
Attribute formtarget

The place to display the response from submitting the form. It overrides the target attribute of the button's form owner.

type: string - string | undefined
Property fullWidth
Attribute full-width

Iftrue , the button will fill the width of the container.

type: boolean - boolean | undefined
Default: false
Property href
Attribute href

The URL that the link points to. This will render the button as an "a" tag.

type: string - string | undefined
Property hreflang
Attribute hreflang

The human language of the linked URL.

type: string - string | undefined
Property loading
Attribute loading

Iftrue , the button will be in loading state.

type: boolean - boolean | undefined
Default: false
Property monochrome
Attribute monochrome

Iftrue , the button will display as monochromatic in eitherlight ordark theme.

type: boolean - boolean | undefined
Default: false
Property multiple
Attribute multiple

IffileUpload is set totrue , this boolean determines whether multiple files are accepted.

type: boolean - boolean | undefined
Default: false
Property referrerpolicy
Attribute referrerpolicy

How much of the referrer to send when following the link.

type: ReferrerPolicy - "" | "no-referrer" | "no-referrer-when-downgrade" | "origin" | "origin-when-cross-origin" | "same-origin" | "strict-origin" | "strict-origin-when-cross-origin" | "unsafe-url" | undefined
Property rel
Attribute rel

The relationship of the linked URL as space-separated link types.

type: string - string | undefined
Property selectedFiles

The list of the files that have been selected by a user.

type: FileList - FileList | undefined
Property size
Attribute size

The size of the button to be displayed.

type: IcSizes - "large" | "medium" | "small" | undefined
Default: "medium"
Property target
Attribute target

The place to display the linked URL, as the name for a browsing context (a tab, window, or iframe).

type: string - string | undefined
Property theme
Attribute theme

Sets the theme color to the dark or light theme color. "inherit" will set the color based on the system settings or ic-theme component.

type: IcThemeMode - "dark" | "inherit" | "light" | undefined
Default: "inherit"
Property tooltipPlacement
Attribute tooltip-placement

The position of the tooltip in relation to the button.

type: IcButtonTooltipPlacement - "bottom" | "left" | "right" | "top" | undefined
Default: "bottom"
Property transparentBackground
Attribute transparent-background

Iftrue , the secondary variant of button will have a transparent background rather than white.

type: boolean - boolean | undefined
Default: true
Property type
Attribute type

The type of the button.

type: IcButtonTypes - "button" | "reset" | "submit" | undefined
Default: "button"
Property variant
Attribute variant

The variant of the button to be displayed.

type: IcButtonVariants - "destructive" | "icon" | "icon-destructive" | "icon-primary" | "icon-secondary" | "icon-tertiary" | "primary" | "secondary" | "tertiary" | undefined
Default: "primary"

Slots

A slot allows for any type of element or markup to be passed into and rendered within a web component. This creates more flexibility than using a prop which must take a specific type of data.

Content can be slotted into a component by adding it as a top-level child of the component.

Slots can have a name to identify them. These specify which slot the content will be inserted into, and therefore where it will be rendered and how it will be used within the component. The name of the slot to be used can be specified by passing it via a slot attribute on the slotted content.

Read more about slots .


Name Description
Slot badge
Badge component overlaying the top right of the button.
Slot left-icon
Content will be placed to the left of the button label.
Slot right-icon
Content will be placed to the right of the button label.
Slot router-item
Handle routing by nesting your routes in this slot. Setting loading to true will have no impact on this slot.
Slot top-icon
Content will be placed above the button label.
Slot badge
Badge component overlaying the top right of the button.
Slot left-icon
Content will be placed to the left of the button label.
Slot right-icon
Content will be placed to the right of the button label.
Slot router-item
Handle routing by nesting your routes in this slot. Setting loading to true will have no impact on this slot.
Slot top-icon
Content will be placed above the button label.

CSS Custom Properties

Name Description
--height The height of the button.
--min-width Minimum width of the button.
--height The height of the button.
--min-width Minimum width of the button.

Events

All components also accept native events supported by the DOM, such as onClick and onKeyDown .

Name Description Signature
Web component icBlur
React onIcBlur
Emitted when button has blur
void
Web component icFileSelection
React onIcFileSelection
If `fileUpload` is set to `true`, this will be emitted when a file is selected in the native explorer.
FileList
Web component icFocus
React onIcFocus
Emitted when button has focus
void
Web component icBlur
React onIcBlur
Emitted when button has blur
void
Web component icFileSelection
React onIcFileSelection
If `fileUpload` is set to `true`, this will be emitted when a file is selected in the native explorer.
FileList
Web component icFocus
React onIcFocus
Emitted when button has focus
void

Methods

Name Description Signature
Method setFocus
Sets focus on the native `button`.
setFocus() => Promise<void>
Method setFocus
Sets focus on the native `button`.
setFocus() => Promise<void>

Variants

Other states

Interactive example

Add to order Loading button
<ic-buttonvariant="primary"disabled="true">Add to order</ic-button>
<ic-buttonvariant="secondary"loading="true">Loading button</ic-button>
<ic-buttonvariant="primary"dropdown="true">Add to order</ic-button>

With icon

Interactive example

Refresh order status
<ic-buttonvariant="primary">
<svg
slot="left-icon"
xmlns="http://www.w3.org/2000/svg"
height="24"
viewBox="0 0 24 24"
width="24"
fill="#000000"
>
<pathd="M0 0h24v24H0V0z"fill="none"></path>
<pathd="M17.65 6.35C16.2 4.9 14.21 4 12 4c-4.42 0-7.99 3.58-7.99 8s3.57 8 7.99 8c3.73 0 6.84-2.55 7.73-6h-2.08c-.82 2.33-3.04 4-5.65 4-3.31 0-6-2.69-6-6s2.69-6 6-6c1.66 0 3.14.69 4.22 1.78L13 11h7V4l-2.35 2.35z"></path>
</svg>
Refresh order status
</ic-button>

Icon Button

When using an icon button, refer to the guidance of using tooltips . When disabling tooltips, provide a suitablearia-label ortitle to provide context to screen readers.

Interactive example

<ic-button
variant="icon-primary"
aria-label="refresh"
>
<svg
xmlns="http://www.w3.org/2000/svg"
width="24"
height="24"
viewBox="0 0 24 24"
fill="#000000"
>
<pathd="M0 0h24v24H0V0z"fill="none"></path>
<pathd="M17.65 6.35C16.2 4.9 14.21 4 12 4c-4.42 0-7.99 3.58-7.99 8s3.57 8 7.99 8c3.73 0 6.84-2.55 7.73-6h-2.08c-.82 2.33-3.04 4-5.65 4-3.31 0-6-2.69-6-6s2.69-6 6-6c1.66 0 3.14.69 4.22 1.78L13 11h7V4l-2.35 2.35z"></path>
</svg>
</ic-button>
<ic-button
variant="icon-secondary"
aria-label="refresh"
>
<svg
xmlns="http://www.w3.org/2000/svg"
width="24"
height="24"
viewBox="0 0 24 24"
fill="#000000"
>
<pathd="M0 0h24v24H0V0z"fill="none"></path>
<pathd="M17.65 6.35C16.2 4.9 14.21 4 12 4c-4.42 0-7.99 3.58-7.99 8s3.57 8 7.99 8c3.73 0 6.84-2.55 7.73-6h-2.08c-.82 2.33-3.04 4-5.65 4-3.31 0-6-2.69-6-6s2.69-6 6-6c1.66 0 3.14.69 4.22 1.78L13 11h7V4l-2.35 2.35z"></path>
</svg>
</ic-button>
<ic-button
variant="icon-tertiary"
aria-label="refresh"
>
<svg
xmlns="http://www.w3.org/2000/svg"
width="24"
height="24"
viewBox="0 0 24 24"
fill="#000000"
>
<pathd="M0 0h24v24H0V0z"fill="none"></path>
<pathd="M17.65 6.35C16.2 4.9 14.21 4 12 4c-4.42 0-7.99 3.58-7.99 8s3.57 8 7.99 8c3.73 0 6.84-2.55 7.73-6h-2.08c-.82 2.33-3.04 4-5.65 4-3.31 0-6-2.69-6-6s2.69-6 6-6c1.66 0 3.14.69 4.22 1.78L13 11h7V4l-2.35 2.35z"></path>
</svg>
</ic-button>
<ic-button
variant="icon-destructive"
aria-label="refresh"
>
<svg
xmlns="http://www.w3.org/2000/svg"
width="24"
height="24"
viewBox="0 0 24 24"
fill="#000000"
>
<pathd="M0 0h24v24H0V0z"fill="none"></path>
<pathd="M17.65 6.35C16.2 4.9 14.21 4 12 4c-4.42 0-7.99 3.58-7.99 8s3.57 8 7.99 8c3.73 0 6.84-2.55 7.73-6h-2.08c-.82 2.33-3.04 4-5.65 4-3.31 0-6-2.69-6-6s2.69-6 6-6c1.66 0 3.14.69 4.22 1.78L13 11h7V4l-2.35 2.35z"></path>
</svg>
</ic-button>
<ic-button
variant="icon"
aria-label="you can disable tooltips on icon buttons"
disable-tooltip="true"
>
<svg
xmlns="http://www.w3.org/2000/svg"
width="24"
height="24"
viewBox="0 0 24 24"
fill="#000000"
>
<pathd="M0 0h24v24H0V0z"fill="none"></path>
<pathd="M17.65 6.35C16.2 4.9 14.21 4 12 4c-4.42 0-7.99 3.58-7.99 8s3.57 8 7.99 8c3.73 0 6.84-2.55 7.73-6h-2.08c-.82 2.33-3.04 4-5.65 4-3.31 0-6-2.69-6-6s2.69-6 6-6c1.66 0 3.14.69 4.22 1.78L13 11h7V4l-2.35 2.35z"></path>
</svg>
</ic-button>

Tooltip

Interactive example

Button With Title Different positions
<ic-buttonvariant="primary"title="We can add tooltips to text buttons">Button With Title</ic-button>
<ic-button
variant="primary"
title="the tooltipPlacement prop allows us to change the location of the tooltip"
tooltip-placement="right"
>
Different positions
</ic-button>

Sizing

Interactive example

Add to order Add to order Add to order
<ic-buttonvariant="primary"size="small">Add to order</ic-button>
<ic-buttonvariant="primary">Add to order</ic-button>
<ic-buttonvariant="primary"size="large">Add to order</ic-button>

Colour variants

Interactive example

Add to order Add to order Add to order
<ic-buttonvariant="primary">Add to order</ic-button>
<ic-buttonvariant="primary"monochrome="true">Add to order</ic-button>
<ic-buttonvariant="primary"theme="dark"monochrome="true">Add to order</ic-button>

File upload

Interactive example

Upload a file Upload multiple files
<ic-button
variant="primary"
id="file-button-single"
file-upload="true"
accept=".doc, text/plain, .json, .png"
>
Upload a file
</ic-button>
<ic-button
variant="primary"
id="file-button-multiple"
file-upload="true"
multiple="true"
accept=".doc, text/plain, .json, .png"
>
Upload multiple files
</ic-button>

Interactive example

<ic-button
dropdown="true"
variant="primary"
id="dropdown-button-popover"
onclick="handleClick()"
>
Actions
</ic-button>
<ic-popover-menu
anchor="dropdown-button-popover"
aria-label="popover"
id="dropdown-button-popover-menu"
>
<ic-menu-grouplabel="Sort">
<ic-menu-itemlabel="Sort ascending">
<svg
slot="icon"
xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 24 24"
>
<path
d="M7.03 9.97H11.03V18.89L13.04 18.92V9.97H17.03L12.03 4.97Z"
/>
</svg>
</ic-menu-item>
<ic-menu-itemlabel="Sort descending">
<svg
slot="icon"
xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 24 24"
>
<pathd="M7.03 13.92H11.03V5L13.04 4.97V13.92H17.03L12.03 18.92Z"/>
</svg>
</ic-menu-item>
</ic-menu-group>
<ic-menu-itemlabel="Filter"variant="toggle">
<svgslot="icon"xmlns="http://www.w3.org/2000/svg"viewBox="0 0 24 24">
<path
d="M2.39 1.73L1.11 3L9 10.89V15.87C8.96 16.16 9.06 16.47 9.29 16.7L13.3 20.71C13.69 21.1 14.32 21.1 14.71 20.71C14.94 20.5 15.04 20.18 15 19.88V16.89L20.84 22.73L22.11 21.46L15 14.35V14.34L13 12.35L11 10.34L4.15 3.5L2.39 1.73M6.21 3L8.2 5H16.96L13.11 9.91L15 11.8V10.75L19.79 4.62C20.13 4.19 20.05 3.56 19.62 3.22C19.43 3.08 19.22 3 19 3H6.21M11 12.89L13 14.89V17.58L11 15.58V12.89Z"
/>
</svg>
</ic-menu-item>
<ic-menu-grouplabel="Manage columns">
<ic-menu-itemlabel="Hide column"variant="toggle">
<svg
slot="icon"
xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 24 24"
>
<path
d="M2,5.27L3.28,4L20,20.72L18.73,22L15.65,18.92C14.5,19.3 13.28,19.5 12,19.5C7,19.5 2.73,16.39 1,12C1.69,10.24 2.79,8.69 4.19,7.46L2,5.27M12,9A3,3 0 0,1 15,12C15,12.35 14.94,12.69 14.83,13L11,9.17C11.31,9.06 11.65,9 12,9M12,4.5C17,4.5 21.27,7.61 23,12C22.18,14.08 20.79,15.88 19,17.19L17.58,15.76C18.94,14.82 20.06,13.54 20.82,12C19.17,8.64 15.76,6.5 12,6.5C10.91,6.5 9.84,6.68 8.84,7L7.3,5.47C8.74,4.85 10.33,4.5 12,4.5M3.18,12C4.83,15.36 8.24,17.5 12,17.5C12.69,17.5 13.37,17.43 14,17.29L11.72,15C10.29,14.85 9.15,13.71 9,12.28L5.6,8.87C4.61,9.72 3.78,10.78 3.18,12Z"
/>
</svg>
</ic-menu-item>
<ic-menu-itemlabel="Column width">
<svg
slot="icon"
xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 24 24"
>
<pathd="M21,9L17,5V8H10V10H17V13M7,11L3,15L7,19V16H14V14H7V11Z"/>
</svg>
</ic-menu-item>
</ic-menu-group>
</ic-popover-menu>

Last reviewed 31 May 2024 .
Navigated to Button - Intelligence Community Design System