Button

Button element to handle click events

Basic Usage

<script setup>
import { Button } from '@vrgl/vergil/components'
</script>

<template>
    <Button>Keep it Clean!</Button>
</template>

Props

Label

label: string

MiniMarkup

Simple Button text content can be specified through the default slot or the label prop. The slot content overrides the label prop.

<Button label="Click"/>

Variant

variant: ('solid' | 'soft' | 'subtle') = 'solid'

Mask

mask: ('ghost' | 'form-field')

Outline

outline: (boolean | 'subtle' | 'regular' | 'strong')

The 'regular' and true values are equivalent. For the solid variant, only buttons with mask are affected.

Fill

fill: boolean

only for masked buttons

Underline

underline: boolean

Icon

icon: string

alias:

icon-left

<Button icon="rocket_launch"/>

Icon Right

icon-right: string

<Button label="Omega" icon-right="special_character"/>

Squared

squared: boolean

Adding squared sets padding to the same value on all sides.

Link to

link-to: RouteLocationRaw

The link-to prop instructs Button to mount an a element instead of a button. In addition, Button supports RouterLink and NuxtLink by automatically rendering whichever is available when link-to is used (NuxtLink has precedence over RouterLink).

If a plain a element is mounted, link-to becomes its href attribute. Otherwise, link-to is equivalent to RouterLink's to prop.

<Button label="Link" link-to="/path"/>

Link

Link options

link-options: AnchorHTMLAttributes | Omit<RouterLinkProps, 'to'> | Omit<NuxtLinkProps, 'to' | 'href'>

Additional attributes or props for underlying a element, or RouterLink or NuxtLink components if link-to is provided.

<Button
    label="External Link"
    link-to="/path"
    :link-options="{ target: '_blank' }"
/>

External Link

Link underline

link-underline: boolean

Underlines Button's label on hover when link-to is provided.

<Button label="Link underline" link-to="/path" link-underline/>

Link underline

Theme

theme: Theme = 'brand'

Interaction Theme

interaction-theme: Theme

Size

size: ('xs' | 'sm' | 'md' | 'lg' | 'xl') = 'md'

Radius

radius: ('none' | 'sm' | 'md' | 'lg' | 'full') = 'md'

Spacing

spacing: ('compact' | 'expanded') = ''

Disabled

disabled: boolean

Loading

loading: boolean

Button group

An element with a button-group class can be used to group Button components together:

<div class="button-group">
    <Button variant="soft" outline squared theme="neutral" interaction-theme="brand" icon="edit"/>
    <Button variant="soft" outline squared theme="neutral" interaction-theme="danger" icon="delete"/>
</div>

Exposed

Link instance

When link-to is provided and RouterLink or NuxtLink is rendered, a corresponding useLink or useNuxtLink instance is exposed.

The exposed link instance may be used, for example, to update Button props based on whether the link is active:

<script setup>
import { useExposed } from '@vrgl/vergil'
const exposed = useExposed()
</script>

<template>
    <Button :exposed link-to="/"
        :theme="exposed.isActive ? 'brand' : 'neutral'"
    />
</template>

WARNING

If link-to is an object defined in-template, an infinite loop may be generated if template-tracked exposed properties are triggered because when the template is re-rendered a new object may be created for link-to. In that case, Button internally creates and exposes a new link instance, and triggers the exposed object, which in turn triggers another template re-render, and so on. To prevent this, defining a link-to object directly in the template should be avoided:

<script setup>
import { useExposed } from '@vrgl/vergil'
const exposed = useExposed()
const linkTo = {/* ... */}
</script>

<template>
    <Button :exposed link-to="{/* ... */}" v-bind="f(exposed)"/>
    <Button :exposed :link-to v-bind="f(exposed)"/>
</template>

API Reference

Props

prop	type	default
label	string
variant	'solid' | 'soft' | 'subtle'	'solid'
mask	'ghost' | 'form-field'
outline	boolean | 'subtle' | 'regular' | 'strong'
underline	boolean
fill	boolean
icon	string
iconLeft	string
iconRight	string
squared	boolean	false
disabled	boolean	false
loading	boolean	false
linkTo	RouteLocationRaw
linkOptions	AnchorHTMLAttributes | Omit<RouterLinkProps, 'to'> | Omit<NuxtLinkProps, 'to' | 'href'>
linkUnderline	boolean
descendant	boolean
theme	'brand' | 'user' | 'ok' | 'info' | 'warn' | 'danger' | 'neutral'	'brand'
interactionTheme	'brand' | 'user' | 'ok' | 'info' | 'warn' | 'danger' | 'neutral'
size	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'
radius	'none' | 'sm' | 'md' | 'lg' | 'full'	'md'
spacing	'' | 'compact' | 'extended'	''
exposed	object

Configuration options

Button's configuration options allow to overwrite some Button props' default values and may be overwritten under the button root-level configuration option.

button.<option>	type	default	global
variant	'solid' | 'soft' | 'subtle'	'solid'
<variant>.mask	'ghost' | 'form-field'
<variant>.outline	boolean | 'subtle' | 'regular' | 'strong'
<variant>.underline	boolean
<variant>.fill	boolean
squared	boolean
theme	theme		✅
size	size		✅
radius	radius		✅
spacing	spacing		✅

Anatomy

<button.button/>

<span.button-backdrop/>

<div.button-content/>

<Icon.icon/>

<slot name="default"/>

<Icon.icon/>

<div.button-loader/>

<span.button-spinner/>

<p.button-label/>

<slot name="aside"/>