Skip to main content

Button

Used to trigger an action or event.

Submit feedback
Edit this page
github
View source code
figma
View design
import { Button } from '@uhg-abyss/mobile';
        <Button>Click Here!</Button>

        Button Types and Variants​

        Button provides distinct visual styles through separate type and variant props:

        • Use the type prop to specify the button style category: filled, outline, or text.
        • Use the variant prop to indicate purpose: brand (primary actions), neutral (secondary actions), destructive (dangerous actions), or inverse (on dark backgrounds).

        By default, brand variant and filled type are enabled.

        Size​

        Use the size prop to change the size of the button. The size prop can take in either large or small. The default value is large. To better visualize the difference, the Layout is preventing the large from taking up the full screen.

        Icon Position​

        The iconPosition prop controls where icons appear in your button. There are three options:

        • trailing (default): Places the icon after the button text
        • leading: Places the icon before the button text
        • iconOnly: Creates a small circular button with only the icon and no text

        Icon-Only Buttons​

        iconPosition="iconOnly" creates button with no text.

        Icons​

        Button provides icon support through the icon prop. You can display icons in different ways:

        Using an Icon Object: Provide an icon object with properties:

        • name: The icon name (from IconSymbol)
        • variant: icon style ('filled' or 'outlined')

        Using a String Name: Provide the icon name as a valid IconSymbol name string.

        Using a React Node: For advanced use cases, you can provide a custom Icon component.

        Using a Function: Use a function that returns a React node, which receives the button's pressed state and allows Button to set the color according to Abyss color mappings, or override them.

        Loading​

        When isLoading is set to true, a spinner indicates that an action is in progress, and onPress events are disabled.

        Disabled​

        Use the isDisabled prop to render the button in a non-interactive state. A disabled button cannot be in a loading state.

        Button Props

        Prop NameTypeDefaultDescription
        childrennode-The contents of the button component
        icon{ name: string, variant?: string } | React.ReactNode | string | Function-Configuration for an icon to display in the button
        iconPosition'leading' | 'trailing' | 'iconOnly'falseWhen true, displays only the icon in a circular button
        isDisabledbooleanfalseFlag to disable the button
        isLoadingbooleanfalseFlag to show loading spinner within the button
        onPressfunction-Callback fired when the button is pressed
        size'large' | 'small'largeSet the size of the button
        submitbooleanfalseFlag to indicate the button is a form submit button
        type'filled' | 'outline' | 'text'filledThe style category of the button
        variant'brand' | 'neutral' | 'destructive' | 'inverse'brandThe color scheme of the button

        Button Classes

        Class NameDescription
        abyss-button-iconButton icon element
        abyss-button-labelButton label element
        abyss-button-loading-spinnerButton spinner element
        abyss-button-rootButton root element

        Button Tokens

        Token NameValue
        button.color.surface.container.filled-brand.rest
        #002677
        button.color.surface.container.filled-brand.active
        #00184D
        button.color.surface.container.filled-neutral.rest
        #323334
        button.color.surface.container.filled-neutral.active
        #000000
        button.color.surface.container.filled-destructive.rest
        #990000
        button.color.surface.container.filled-destructive.active
        #890000
        button.color.surface.container.filled-inverse.rest
        #FFFFFF
        button.color.surface.container.filled-inverse.active
        #F3F3F3
        button.color.surface.container.filled-disabled
        #CBCCCD
        button.color.surface.container.outline-brand.rest
        #FFFFFF
        button.color.surface.container.outline-brand.active
        #EDF3FB
        button.color.surface.container.outline-neutral.rest
        #FFFFFF
        button.color.surface.container.outline-neutral.active
        #F3F3F3
        button.color.surface.container.outline-destructive.rest
        #FFFFFF
        button.color.surface.container.outline-destructive.active
        #FCF0F0
        button.color.surface.container.outline-disabled
        #F3F3F3
        button.color.surface.container.text-brand.active
        rgba(255, 255, 255, 0)
        button.color.surface.loading-spinner.filled-brand
        #FFFFFF
        button.color.surface.loading-spinner.outline-brand
        #002677
        button.color.surface.loading-spinner.text-brand
        #196ECF
        button.color.surface.loading-spinner.filled-neutral
        #FFFFFF
        button.color.surface.loading-spinner.outline-neutral
        #4B4D4F
        button.color.surface.loading-spinner.text-neutral
        #4B4D4F
        button.color.surface.loading-spinner.filled-destructive
        #FFFFFF
        button.color.surface.loading-spinner.outline-destructive
        #990000
        button.color.surface.loading-spinner.text-destructive
        #990000
        button.color.surface.loading-spinner.outline-inverse
        #FFFFFF
        button.color.surface.loading-spinner.filled-inverse
        #323334
        button.color.surface.loading-spinner.text-inverse
        #FFFFFF
        button.color.text.label.filled-brand
        #FFFFFF
        button.color.text.label.filled-destructive
        #FFFFFF
        button.color.text.label.filled-neutral
        #FFFFFF
        button.color.text.label.filled-inverse
        #323334
        button.color.text.label.filled-disabled
        #4B4D4F
        button.color.text.label.outline-brand
        #002677
        button.color.text.label.outline-neutral.rest
        #323334
        button.color.text.label.outline-neutral.active
        #000000
        button.color.text.label.outline-destructive
        #990000
        button.color.text.label.outline-inverse.rest
        #FFFFFF
        button.color.text.label.outline-inverse.active
        #A5DFE7
        button.color.text.label.outline-disabled
        #929496
        button.color.text.label.text-brand.rest
        #0C55B8
        button.color.text.label.text-brand.active
        #003A8D
        button.color.text.label.text-neutral.rest
        #323334
        button.color.text.label.text-neutral.active
        #000000
        button.color.text.label.text-inverse.rest
        #FFFFFF
        button.color.text.label.text-inverse.active
        #A5DFE7
        button.color.text.label.text-destructive.rest
        #990000
        button.color.text.label.text-destructive.active
        #890000
        button.color.text.label.text-disabled
        #929496
        button.color.icon.filled-brand
        #FFFFFF
        button.color.icon.filled-neutral
        #FFFFFF
        button.color.icon.filled-destructive
        #FFFFFF
        button.color.icon.filled-inverse
        #4B4D4F
        button.color.icon.filled-disabled
        #4B4D4F
        button.color.icon.outline-brand
        #002677
        button.color.icon.outline-neutral
        #323334
        button.color.icon.outline-destructive
        #990000
        button.color.icon.outline-inverse.rest
        #FFFFFF
        button.color.icon.outline-inverse.active
        #A5DFE7
        button.color.icon.outline-disabled
        #929496
        button.color.icon.text-brand.rest
        #196ECF
        button.color.icon.text-brand.active
        #004BA0
        button.color.icon.text-neutral.rest
        #323334
        button.color.icon.text-neutral.active
        #000000
        button.color.icon.text-inverse.rest
        #FFFFFF
        button.color.icon.text-inverse.active
        #A5DFE7
        button.color.icon.text-destructive.rest
        #990000
        button.color.icon.text-destructive.active
        #890000
        button.color.icon.text-disabled
        #929496
        button.color.border.container.outline-brand
        #002677
        button.color.border.container.outline-neutral
        #323334
        button.color.border.container.outline-destructive
        #990000
        button.color.border.container.outline-inverse.rest
        #FFFFFF
        button.color.border.container.outline-inverse.active
        #A5DFE7
        button.color.border.container.outline-disabled
        #929496
        button.border-radius.all.container.with-text
        500
        button.border-radius.all.container.icon-only
        4
        button.border-width.all.container
        1
        button.sizing.all.icon.with-text
        16
        button.sizing.all.icon.icon-only
        24
        button.sizing.all.min.container.icon-only
        40
        button.sizing.height.min.container.lg
        48
        button.sizing.height.min.container.sm
        32
        button.spacing.padding.vertical.container.sm
        4
        button.spacing.padding.vertical.container.lg
        12
        button.spacing.padding.horizontal.container.sm
        16
        button.spacing.padding.horizontal.container.lg
        24
        button.spacing.padding.all.container.icon-only
        8
        button.spacing.gap.horizontal.container
        8

        Variant Mappings​

        This section explains how Button props map from V1 to V2 and shows concrete examples to make migration easier.

        The variant props were renamed.

        • primary -> brand (Brand is the default)
        • secondary -> neutral
        • tertiary -> Use the prop: type="text" The color is determined by the variant
        • destructive -> destructive and type="outline"
        • alt -> inverse

        Example:

        // v1
        <Button variant="primary">Click Here!</Button>
        

        // v2
        <Button variant="brand">Click Here!</Button>

        Type vs Variant in V2​

        In v2 the type prop controls the visual category (filled | outline | text) while variant controls purpose/semantic color (brand | neutral | destructive | inverse). If you previously relied on variant to imply filled vs outline, add an explicit type prop in V2. If you used type in the v1 Button to submit a form, in v2 you can use the new submit boolean prop.

        Example:

        // v1 intent: a secondary/outline button with the primary color (legacy)
        <Button variant="secondary">Secondary</Button>
        

        // v2: an outlined button with the brand color (brand prop optional here due to default)
        <Button type="outline" variant="brand">Secondary</Button>
        

        // v1 intent: a button that submits a form
        <Button type="submit">Submit</Button>
        

        // v2: a button that submits a form
        <Button submit>Submit</Button>
        • before / after -> use icon + iconPosition (leading/trailing)
        • rounded -> use iconPosition="iconOnly" and icon object

        There are multiple ways to add icons in the new button, see main doc page.

        Examples:

        // v1
        <Button before={<IconSymbol icon="home" />}>Home</Button>
        

        // v2
        <Button icon={{ name: 'home' }} iconPosition="leading">Home</Button>
        

        // v1
        <Button rounded before={<IconSymbol icon="add" />} />
        

        // v2
        <Button icon={{ name: 'add' }} iconPosition="iconOnly" accessibilityLabel="Add" />

        Button Classes

        V2V1Status
        button-icon-Added
        button-labelbutton-labelUnchanged
        button-loading-spinner-Added
        button-rootbutton-rootUnchanged

        Button Props

        V2V1Status
        childrenchildrenUnchanged
        iconbeforeRenamed
        iconafterRenamed
        iconPosition-Added
        isDisabledisDisabledUnchanged
        isLoading-Added
        onPressonPressUnchanged
        -roundedRemoved
        sizesizeModified
        submit-Added
        typetypeModified
        variantvariantModified

        Button Tokens

        V2V1Status
        button.border-radius.all.container.icon-only-Unchanged
        button.border-radius.all.container.with-text-Unchanged
        button.border-width.all.container-Unchanged
        -button.color.border.container.alt.activeRemoved
        -button.color.border.container.alt.restRemoved
        -button.color.border.container.destructiveRemoved
        button.color.border.container.outline-brand-Added
        button.color.border.container.outline-destructive-Added
        button.color.border.container.outline-disabled-Added
        button.color.border.container.outline-inverse-Added
        button.color.border.container.outline-neutral-Added
        -button.color.border.container.secondaryRemoved
        -button.color.icon.alt.activeRemoved
        -button.color.icon.alt.restRemoved
        button.color.icon.filled-brand-Added
        button.color.icon.filled-destructive-Added
        button.color.icon.filled-disabled-Added
        button.color.icon.filled-inverse-Added
        button.color.icon.filled-neutral-Added
        -button.color.icon.interactive.disabled.primaryRemoved
        button.color.icon.outline-brand-Added
        button.color.icon.outline-destructive-Added
        button.color.icon.outline-disabled-Added
        button.color.icon.outline-inverse-Added
        button.color.icon.outline-neutral-Added
        -button.color.icon.status.errorRemoved
        -button.color.icon.tertiary.activeRemoved
        -button.color.icon.tertiary.restRemoved
        button.color.icon.text-brand-Added
        button.color.icon.text-destructive-Added
        button.color.icon.text-disabled-Added
        button.color.icon.text-inverse-Added
        button.color.icon.text-neutral-Added
        -button.color.surface.container.destructiveRemoved
        -button.color.surface.container.disabledRemoved
        button.color.surface.container.filled-brand-Added
        button.color.surface.container.filled-destructive-Added
        button.color.surface.container.filled-disabled-Added
        button.color.surface.container.filled-inverse-Added
        button.color.surface.container.filled-neutral-Added
        button.color.surface.container.loading-spinner.filled-inverse-Added
        button.color.surface.container.loading-spinner.outline-destructive-Added
        button.color.surface.container.loading-spinner.outline-neutral-Added
        button.color.surface.container.loading-spinner.text-brand-Added
        button.color.surface.container.loading-spinner.text-destructive-Added
        button.color.surface.container.loading-spinner.text-neutral-Added
        button.color.surface.container.outline-brand-Added
        button.color.surface.container.outline-destructive-Added
        button.color.surface.container.outline-disabled-Added
        button.color.surface.container.outline-neutral-Added
        -button.color.surface.container.primary-icon-onlyRemoved
        -button.color.surface.container.secondaryRemoved
        -button.color.text.label.alt.activeRemoved
        -button.color.text.label.alt.restRemoved
        button.color.text.label.filled-brand-Added
        button.color.text.label.filled-destructive-Added
        button.color.text.label.filled-disabled-Added
        button.color.text.label.filled-inverse-Added
        button.color.text.label.filled-neutral-Added
        button.color.text.label.outline-brand-Added
        button.color.text.label.outline-destructive-Added
        button.color.text.label.outline-disabled-Added
        button.color.text.label.outline-inverse-Added
        button.color.text.label.outline-neutral-Added
        -button.color.text.label.tertiary.activeRemoved
        -button.color.text.label.tertiary.restRemoved
        button.color.text.label.text-brand-Added
        button.color.text.label.text-destructive-Added
        button.color.text.label.text-disabled-Added
        button.color.text.label.text-inverse-Added
        button.color.text.label.text-neutral-Added
        button.sizing.all.icon.icon-only-Unchanged
        button.sizing.all.icon.with-text-Unchanged
        button.sizing.all.min.container.icon-only-Unchanged
        button.sizing.height.min.container.lg-Unchanged
        button.sizing.height.min.container.sm-Unchanged
        button.spacing.gap.horizontal.container-Unchanged
        button.spacing.padding.all.container.icon-only-Unchanged
        button.spacing.padding.horizontal.container.lg-Unchanged
        button.spacing.padding.horizontal.container.sm-Unchanged
        button.spacing.padding.vertical.container.lg-Unchanged
        button.spacing.padding.vertical.container.sm-Unchanged
        Table of Contents