AisButton

Branded button component

Props

Type

The type prop sets the HTML type attribute. Accepted values are: button, submit, and reset. The default value is button.

Variant

The variant prop accepts the standard variants and dictates the button styles. The variants are: primary, secondary, default, plain, info, success, warning, and danger. The default value is primary. The variants are shown here using the hover and pressed effects.

Default

Primary

Secondary

Plain

Info

Success

Warning

Danger

<script setup>
import Example from "@/components/docs/ComponentExample.vue";
import { AisButton } from '@ais-public/ais-components';
import { variants } from '@/util/variants-util';
import { capitalizeFirst } from '@/util/util';
</script>

<template>
  <div class="grid grid-cols-3 md:grid-cols-4 gap-x-4  gap-y-8">
    <Example v-for="variant in variants" :label="capitalizeFirst(variant)">
      <AisButton :variant="variant"
                 hover fast press
      >
        Button
      </AisButton>
    </Example>
  </div>
</template>

Outline

The outline prop can be combined with variant to provide an alternate set of button styles. outline is a boolean prop that can be added without a value. outline variants use a lighter background with a visible border.

Default

Primary

Secondary

Plain

Info

Success

Warning

Danger

<script setup>
  import { AisButton } from '@ais-public/ais-components';
  import Example from '@/components/docs/ComponentExample.vue';
  import { variants } from '@/util/variants-util';
  import { capitalizeFirst } from '@/util/util';
</script>

<template>
  <div class="grid grid-cols-3 md:grid-cols-4 gap-x-4  gap-y-8">
    <Example v-for="variant in variants" :label="capitalizeFirst(variant)">
      <AisButton :variant="variant" outline
                 hover fast press
      >
        Outline
      </AisButton>
    </Example>
  </div>
</template>

Alternate

The alternate prop has been deprecated and has been replaced by outline. Please update your usages as alternate will be removed.

Size

Thesize prop controls the button size. The accepted values are: xs, sm, md, lg, xl, and xxl. The default value is md and size xl matches UIDS SiteNow buttons. Forms should use md, lg, or xl leaving the extremes for more specialized interfaces. Buttons smaller than md should not use the font caps.

xxl

xl

lg

md

sm

xs

<template>
  <div class="grid gap-y-8">
    <div class="flex flex-wrap items-end justify-start gap-x-6 gap-y-8">
      <Example label="xxl">
        <AisButton size="xxl" variant="secondary" outline press>2X-large</AisButton>
      </Example>
      <Example label="xl">
        <AisButton size="xl" variant="secondary" outline press>X-large</AisButton>
      </Example>

      <Example label="lg">
        <AisButton size="lg" variant="secondary" outline press>Large</AisButton>
      </Example>

      <Example label="md">
        <AisButton size="md" variant="secondary" outline press>Medium</AisButton>
      </Example>

      <Example label="sm">
        <AisButton size="sm" variant="secondary" font="sans"  outline press>Small</AisButton>
      </Example>

      <Example label="xs">
        <AisButton size="xs" variant="secondary" font="sans" outline press>X-small</AisButton>
      </Example>
    </div>
  </div>
</template>

<script setup>
  import { AisButton } from '@ais-public/ais-components';
  import Example from "@/components/docs/ComponentExample.vue";
</script>

Font

The font prop sets the button's font. It will accept one of our three brand fonts: caps, serif, and sans. caps is the default value. (Link to Typography page.)

Featured, stand-alone buttons such as form controls and calls to action should use caps. Buttons displayed in groups or at smaller sizes should consider sans.

caps

serif

sans

caps

serif

sans

<template>
  <div class="grid gap-y-8">
    <div class="flex items-end justify-around">
      <Example label="caps">
        <AisButton font="caps" variant="secondary" icon="save" press>Caps</AisButton>
      </Example>

      <Example label="serif">
        <AisButton font="serif" variant="secondary" icon="save" press>Serif</AisButton>
      </Example>

      <Example label="sans">
        <AisButton font="sans" variant="secondary" icon="save" press>Sans Button</AisButton>
      </Example>
    </div>
    <div class="flex items-end justify-around">
      <Example label="caps">
        <AisButton font="caps" variant="secondary" icon="save" outline press>Caps</AisButton>
      </Example>

      <Example label="serif">
        <AisButton font="serif" variant="secondary" icon="save" outline press>Serif</AisButton>
      </Example>

      <Example label="sans">
        <AisButton font="sans" variant="secondary" icon="save" outline press>Sans Button</AisButton>
      </Example>
    </div>

  </div>
</template>

<script setup>
import { AisButton } from '@ais-public/ais-components';
import Example from '@/components/docs/ComponentExample.vue';
</script>

Disabled

The disabled prop is a boolean flag that will disable a button via the HTML disabled attribute.

Primary

Secondary

Default

Plain

Primary

Secondary

Default

Plain

<template>
  <div class="grid gap-y-8">
    <div class="grid grid-cols-4 gap-4">
      <Example label="Primary">
        <AisButton variant="primary" disabled>Disabled</AisButton>
      </Example>

      <Example label="Secondary">
        <AisButton variant="secondary" disabled>Disabled</AisButton>
      </Example>

      <Example label="Default">
        <AisButton variant="default" disabled>Disabled</AisButton>
      </Example>

      <Example label="Plain">
        <AisButton variant="plain" disabled>Disabled</AisButton>
      </Example>
    </div>
    <div class="grid grid-cols-4 gap-4">
      <Example label="Primary">
        <AisButton variant="primary" outline disabled>Disabled</AisButton>
      </Example>

      <Example label="Secondary">
        <AisButton variant="secondary" outline disabled>Disabled</AisButton>
      </Example>

      <Example label="Default">
        <AisButton variant="default" outline disabled>Disabled</AisButton>
      </Example>

      <Example label="Plain">
        <AisButton variant="plain" outline disabled>Disabled</AisButton>
      </Example>
    </div>
  </div>
</template>

<script setup>
import { AisButton } from '@ais-public/ais-components';
import Example from "@/components/docs/ComponentExample.vue";
</script>

Icon

The optional icon prop accepts either an object imported from the FontAwesome icon packs or a string specifying one of the preloaded, core components. Specifying a value will cause an icon to be displayed alongside the button's text. icon controls the standard location for button icons and should generally be preferred over iconRight.

arrow

asterisk

busy

new

edit

confirm

cancel

save

copy

delete

close

undo

redo

search

filter

info

success

required

error

warning

danger

unknown

person

user

users

group

menu

options

calendar

clock

money

heart

star

locked

unlocked

upload

download

left

right

up

down

first

last

caret-left

caret-right

caret-up

caret-down

file

file-pdf

file-csv

file-excel

file-word

file-powerpoint

file-image

file-video

file-upload

default

primary

secondary

bold

italic

strikethrough

list

list-ol

subscript

superscript

<template>
  <div class="grid grid-cols-4 gap-8">
    <Example v-for="icon in coreIconKeys" :label="icon">
      <AisButton variant="secondary" :icon="icon" fast hover press >
        {{label(icon)}}
      </AisButton>
    </Example>
  </div>
</template>

<script setup>
  import { AisButton } from '@ais-public/ais-components';
  import Example from "@/components/docs/ComponentExample.vue";
  import { coreIconKeys } from "@/components/icon/ais-icons";

  const label = (icon) => !icon.startsWith('caret-') ? icon : icon.replace('caret-', '');
</script>

Icon Right

The optional iconRight prop accepts the same values as icon and will display an icon to the right of the button's text. iconRight is considered a building block for other components. Application developers should prefer the standard icon prop in most cases.

Arrow

<template>
  <div class="flex items-end justify-around">
    <Example label="Arrow">
      <AisButton variant="secondary" iconRight="down">Menu</AisButton>
    </Example>
  </div>
</template>

<script setup>
import { AisButton } from '@ais-public/ais-components';
import Example from '@/components/docs/ComponentExample.vue';
</script>

Busy

Use the busy prop to indicate that the button is busy. When the component is busy, it will not accept additional clicks. This is commonly used when @click triggers an asynchronous action and must await a response.

Click to activate the busy state.

<script setup>
import { AisButton } from '@ais-public/ais-components';
import Example from '@/components/docs/ComponentExample.vue';
import { ref } from 'vue';

const busy = ref(false);

const handleClick = () => {
  console.log('AisButton Clicked!')
  busy.value = true
  setTimeout(() => busy.value = false, 3000)
}
</script>

<template>
  <div class="flex items-end justify-around">
    <Example label="Click to activate the busy state.">
      <AisButton
          @click="handleClick"
          icon="save"
          :busy="busy"
          press
      >
        Save
      </AisButton>
    </Example>
  </div>
</template>

Arrow

The arrow prop is a boolean flag that activates an arrow icon to the right of the button text. This is a form promoted by UIDS for call-to-action buttons.

Arrow

<template>
  <div class="flex items-end justify-around">
    <Example label="Arrow">
      <AisButton variant="secondary" arrow>Apply Now</AisButton>
    </Example>
  </div>
</template>

<script setup>
  import { AisButton } from '@ais-public/ais-components';
  import Example from "@/components/docs/ComponentExample.vue";
</script>

Effects

AisButton accepts a number of boolean props that will enable interactive effects on the button. hover matches the UIDS hover animation. hover fast provides a faster version. press provides a click animation.

hover

hover fast

press

hover & press

<template>
  <div class="grid gap-y-8">
    <div class="flex items-end justify-between">
      <Example label="hover">
        <AisButton hover>Hover</AisButton>
      </Example>

      <Example label="hover fast">
        <AisButton variant="secondary" hover fast>Hover Fast</AisButton>
      </Example>

      <Example label="press">
        <AisButton press>Press</AisButton>
      </Example>

      <Example label="hover & press">
        <AisButton variant="secondary" hover fast press>Hover & Press</AisButton>
      </Example>
    </div>
  </div>
</template>

<script setup>
import { AisButton } from '@ais-public/ais-components';
import Example from "@/components/docs/ComponentExample.vue";
</script>

Block

The block prop makes the button span the full width if its parent. block is a boolean prop that can be added without a value. The default value is false.

<template>
  <div class="grid gap-4 space-y-4">
    <div>
      <AisButton variant="secondary" block>Button</AisButton>
    </div>
  </div>
</template>

<script setup>
  import { AisButton } from '@ais-public/ais-components';
</script>

Rounded

The rounded prop controls the border radius of the button. The accepted values are: true, false, md, lg, and full. The default value is false.

UIDS uses non-rounded buttons. For brand consistency, this form should be preferred for featured, stand-alone buttons such as form controls and calls to action. Developers can play with rounded corners for secondary controls and buttons that need to fade into the background more.

rounded-sm

rounded

rounded-md

rounded-lg

rounded-xl

rounded-2xl

rounded-3xl

rounded-full

<template>
  <div class="grid gap-y-8">
    <div class="grid grid-cols-4 gap-4">
      <Example label="rounded-sm">
        <AisButton rounded="sm" variant="secondary" outline>Button</AisButton>
      </Example>

      <Example label="rounded">
        <AisButton rounded variant="secondary" outline>Button</AisButton>
      </Example>

      <Example label="rounded-md">
        <AisButton rounded="md" variant="secondary" outline>Button</AisButton>
      </Example>

      <Example label="rounded-lg">
        <AisButton rounded="lg" variant="secondary" outline>Button</AisButton>
      </Example>
      <Example label="rounded-xl">
        <AisButton rounded="xl" variant="secondary" outline>Button</AisButton>
      </Example>

      <Example label="rounded-2xl">
        <AisButton rounded="2xl" variant="secondary" outline>Button</AisButton>
      </Example>

      <Example label="rounded-3xl">
        <AisButton rounded="3xl" variant="secondary" outline>Button</AisButton>
      </Example>

      <Example label="rounded-full">
        <AisButton rounded="full" variant="secondary" outline>Button</AisButton>
      </Example>
    </div>
  </div>
</template>

<script setup>
  import { AisButton } from '@ais-public/ais-components';
  import Example from '@/components/docs/ComponentExample.vue';
</script>

To (Route)

The to prop accepts a vue-router location definition. The button will route to location on click. The click event will not be emitted.

keepFocus

keepFocus is a boolean prop. When it is true, the button will keep focus after a click instead of calling blur(). When true, the button will have a focus ring after a click. This allows keyboard users to click multiple times. See the @click example to see it in action.

Events

@click

Bind to @click to handle the button's click event.

0

<script setup>
import { ref } from 'vue';
import { AisButton } from '@ais-public/ais-components';

const counter = ref(0);
</script>

<template>
  <div class="flex gap-1 items-stretch">
    <AisButton outline hover press keep-focus
      variant="secondary"
      icon="down"
      @click="counter--"
    >
      Decrement
    </AisButton>
    <div class="px-4 py-1 text-2xl border border-ui-gray-900">
      {{counter}}
    </div>
    <AisButton outline hover press keep-focus
      variant="secondary"
      icon-right="up"
      @click="counter++"
    >
      Increment
    </AisButton>
  </div>
</template>

Methods

focus()

AisButton exposes a focus() method to programmatically focus the button element. The method can be invoked through a template ref specified on an AisButton component.

<script setup>
import { ref } from 'vue';
import { AisButton } from '@ais-public/ais-components';

const btn = ref(null);
const handleFocus = () => btn.value.focus();
</script>

<template>
  <div class="flex gap-4">
    <AisButton ref="btn" icon="person">
      Button To Focus
    </AisButton>

    <AisButton hover press
        @click="btn.focus()"
       variant="secondary"
    >
      Focus 1
    </AisButton>
    <AisButton hover press
        @click="handleFocus"
        variant="secondary"
    >
      Focus 2
    </AisButton>
  </div>
</template>