ButtonElement

Renders a button.

Basic Usage

<ButtonElement> component can be used in a <Vueform> component:

<template>
  <Vueform>
    <ButtonElement name="button">
      Submit
    </ButtonElement>
  </Vueform>
</template>

Configuration options can be passed over as regular component props. Check out Options section for available configuration options.

Options

Find below the list of options that can use to configure ButtonElement component. Options can be passed to the component via props in inline templates, or in the element's object when using schema.

buttonLabel

  • Type: string|object|function
  • Default: null
<!-- Using string/HTML --->
<ButtonElement button-label="Submit" ... />

<!-- Using component --->
<ButtonElement :button-label="{ template: '<span>Submit</span>' }" ... />

<!-- Using function --->
<ButtonElement name="submit" :button-label="el$ => _.upperFirst(el$.name)" />

The label of the button. Can be defined as a string, a Vue component object with a render function or as a function that receives el$ as its first a param.

Can also be defined via #default slot.

buttonType

  • Type: string
  • Default: button
<ButtonElement button-type="button" ... />
<ButtonElement button-type="anchor" ... />

The type of the button. Can be 'button' or 'anchor'.

buttonClass

  • Type: string|array|object
  • Default: null
<ButtonElement button-class="font-semibold" ... />
<ButtonElement :button-class="['font-semibold']" ... />
<ButtonElement :button-class="{'font-semibold': true}" ... />

Adds Vue style classes to the button's DOM.

loading

  • Type: function|boolean
  • Default: false
<ButtonElement :loading="true" ... />

Triggers the button's loading state.

href

  • Type: string
<ButtonElement button-type="anchor" href="https://vueform.com" ... />

Sets the href attribute of the button when using buttonType: 'anchor'.

target

  • Type: string
  • Default: null
<ButtonElement button-type="anchor" href="https://vueform.com" target="_blank" ... />

Sets the target attribute of the button when using buttonType: 'anchor'.

resets

  • Type: boolean
  • Default: false
<ButtonElement :resets="true" ... />

Whether the button's function is to reset the form.

submits

  • Type: boolean
  • Default: false
<ButtonElement :submits="true" ... />

Whether the button's function is to submit the form.

secondary

  • Type: boolean
  • Default: false
<ButtonElement secondary ... />

Displays the button in secondary color.

danger

  • Type: boolean
  • Default: false
<ButtonElement secondary ... />

Displays the button in danger color.

name

  • Type: string|number
  • Default: undefined
  • Required: true
<ButtonElement name="element" ... />

Sets the element's name.

id

  • Type: string
  • Default: null
<ButtonElement id="field-id" ... />

Sets the id attribute of the button.

disabled

  • Type: function|boolean
  • Default: false
<ButtonElement :disabled="true" ... />
<ButtonElement :disabled="function(el$, form$){ return true }" ... />

Disables the button. If provided as a function it receives the el$ component instance as the first param and form$ as second.

label

  • Type: string|object|function
  • Default: null

Sets a label for the element. Can be defined as a string, a Vue component object with a render function or as a function that receives el$ as its first a param.

Can also be defined via #label slot.

info

  • Type: string
  • Default: null
<ButtonElement label="Info" info="Info" ... />

Renders an ElementInfo component next to the element's label. By default the icon shows the value of info when hovered, which can contain plain text or HTML. The element needs to have a label defined in order for info to be rendered.

Can be also defined via #info slot.

infoPosition

  • Type: string
  • Default: right
<ButtonElement label="Top" info="Top" info-position="top" ... />
<ButtonElement label="Right" info="Right" info-position="right" ... />
<ButtonElement label="Left" info="Left" info-position="left" ... />
<ButtonElement label="Bottom" info="Bottom" info-position="bottom" ... />

Sets the position of the info tooltip.

Can be also defined via #info slot.

description

  • Type: string
  • Default: null
<ButtonElement description="Lorem ipsum dolor sit amet" ... />

Renders the contents of description prop in the ElementDescription component below the button. It can contain plain text or HTML.

Can be also defined via #description slot.

before

  • Type: object|string|number
  • Default: null
<ButtonElement before="Before" ... />

Renders the contents of before in a ElementText component before the button. It can contain plain text or HTML.

Can be also defined via #before slot.

between

  • Type: object|string|number
  • Default: null
<ButtonElement description="Description" between="Between" ... />

Renders the contents of between in a ElementText component between the button and the description. It can contain plain text or HTML.

Can be also defined via #between slot.

after

  • Type: object|string|number
  • Default: null
<ButtonElement description="Description" rules="required" after="After" ... />

Renders the contents of after in a ElementText component after the description and error. It can contain plain text or HTML.

Can be also defined via #after slot.

conditions

  • Type: array
  • Default: []
// field1 - type 'show'
<TextElement name="field1" ... />

// Button 1 - only if field1 == 'show'
<ButtonElement :conditions="[['field1', 'show']]" ... />

// Button 2 - only if field1 != 'show'
<ButtonElement :conditions="[['field1', '!=', 'show']]" ... />

// Button 3 - only if field1 == 'show'
<ButtonElement :conditions="[
  (form$, el$) => form$.el$('field1')?.value === 'show'
]" ... />

Shows or hides an element based on the provided conditions.

If an element's conditions are unmet the element will be hidden and its available property will become false. If hidden, its value will not be part of requestData.

Conditions can be provided as an array, where each item has to be either an array or a function. The element will only become available if all the conditions are fulfilled.

If a condition is provided as an array, the first value must be the path of an other field which value should be watched. The second is an operator that defines the type of comparison. The third is the expected value of the other field.

<ButtonElement name="field" :conditions="[['other_field', '==', 'expected_value']]" ... />

Hint: In case you want to check for equality you might leave the operator and pass the expected value as the second param:

<ButtonElement name="field" :conditions="[['other_field', 'expected_value']]" ... />

Available operators:

  • == - expects equality
  • != - expects inequality
  • not_in - expects not be be among an array of values
  • > - expects the other element's value to be higher
  • >=- expects the other element's value to be higher or equal
  • < - expects the other element's value to be lower
  • <= - expects the other element's value to be lower or equal

The expected value can also be defined as an array in which case any of its values will fulfill the condition.

A condition can also be defined as a function that returns a boolean. The function receives a form$ param (which the root form component). You can use the form$'s el$(path) method or data to reach any element's value within the form:

<ButtonElement name="field" :conditions="[
  function(form$) {
    return form$.el$('other_field').value === 'expected_value'
  },
  function(form$) {
    return form$.data.other_field === 'expected_value'
  }
]" ... />

columns

  • Type: object|string|number
  • Default: null
<ButtonElement label="Label" :columns="{ container: 12, label: 3, wrapper: 12 }" ... />

Sets the size of the container, label and wrapper using the theme's grid system, where the:

  • container is the wrapper DOM that contains both label and wrapper
  • label contains the label
  • wrapper contains the button.
container: 12
label: 3
wrapper: 12

The value of container defines the size of the element's container. 12 will result in full width, 6 in half, 4 in third and so on.

The value of label defines the amount of space the label should take up within the container. If the container is 12 and label is 6 the label is going to take up half the space and the button will the other half (which is calculated automatically). If the container is 6 and label is 6, the label will only take up one forth and the button the rest. In case the label has full width (12) the button will also take up full space instead of becoming zero.

The value of wrapper defines the size of the button wrapper within the space left for it in the container after subtracting the size of the label. If the container is 12 and label is 4 the space left for the button is 8. In this case if the wrapper value is 12 it will take up the full space left for it (which is 8) while if it is changed to 6 it will only take up half the space left for it (4):

<ButtonElement label="Label" :columns="{ container: 12, label: 4, wrapper: 12 }" ... />
<ButtonElement label="Label" :columns="{ container: 12, label: 4, wrapper: 6 }" ... />

Note that while the size of the button wrapper changes, the size of extras like a description or error won't be limited to the wrapper's space. Instead it will take up the full space in the container left after subtracting the size of the label:

<ButtonElement
  label="Label"
  :columns="{ container: 12, label: 4, wrapper: 6 }" 
  description="Lorem ipsum dolor sit amet, consectetur adipiscing elit"
... />

You can set the value of columns as a number in which case the container will receive its value without affecting the default settings of label and wrapper:

<ButtonElement label="Label" :columns="6" ... /> <!-- { container: 6, label: 3, wrapper: 12 } -->

You can as well define column values for different breakpoints using the theme system's breakpoints like sm, md, etc. as keys:

<ButtonElement label="Label" :columns="{
  xs: { container: 12, label: 12, wrapper: 12 },
  sm: { container: 12, label: 4, wrapper: 12 },
  md: 12,
  lg: { container: 12, label: 2, wrapper: 12 }
}" ... />

Default column sizes can be defined globally in vueform.config.js or on form level using columns.

inline

  • Type: boolean
  • Default: false
<ButtonElement :inline="true" ... />

Renders the element and all of its components in a single <span> without applying columns.

size

  • Type: string
  • Default: undefined
<ButtonElement size="sm" ... />
<ButtonElement ... /> <!-- Default size: 'md' -->
<ButtonElement size="lg" ... />

The size of the element and its child components.

view

  • Type: string
  • Default: undefined
<ButtonElement view="alt" ... />

The name of the view to be used for the element and by default for its child components. If undefined the default view will be used. Child component views can be overridden with views option.

Learn more about views here.

views

  • Type: object
  • Default: {}
<ButtonElement :views="{
  ComponentName: 'alt'
}" ... />

The name of the views for the child components.

Learn more about views here.

addClasses

  • Type: object
  • Default: {}
<ButtonElement :add-classes="{
  ComponentName: {
    classname: 'class-value',
    classname: ['class-value'],
    classname: [{'class-value': true}],
  }
}" ... />

Adds classes to any component's class names. The classes can have string or array values. When Vue style classes are used object values must be wrapped in an array.

Learn more about adding classes here.

addClass

  • Type: array|object|string
  • Default: null
<ButtonElement :add-class="{
  classname: 'class-value',
  classname: ['class-value'],
  classname: [{'class-value': true}],
}" ... />

Adds classes to any of ButtonElement component's class names. Classes can have string or array values. When Vue style classes are used object values must be wrapped in an array.

Learn more about adding classes here.

removeClasses

  • Type: object
  • Default: {}
<ButtonElement :remove-classes="{
  ComponentName: {
    classname: ['class-value-1', 'class-value-2']
  }
}" ... />

Removes classes from any class names of any components. The classes to be removed must be listed in an array.

Learn more about removing classes here.

removeClass

  • Type: array|object
  • Default: null
<ButtonElement :remove-class="{
  classname: ['class-value-1', 'class-value-2']
}" ... />

Removes classes from any of ButtonElement component's class names. The classes to be removed must be listed in an array.

Learn more about removing classes here.

replaceClasses

  • Type: object
  • Default: {}
<ButtonElement :replace-classes="{
  ComponentName: {
    classname: {
      'from-class': 'to-class',
      'from-class': ['to-class'],
      'from-class': [{'to-class': true}],
    }
  }
}" ... />

Replaces classes of any class names of any component. The keys are the original class names and the values are the replacements. The keys can only be single classes, while values can contain multiple ones in string or an array. When Vue style classes are used object values must be wrapped in an array.

Learn more about replacing classes here.

replaceClass

  • Type: object
  • Default: null
<ButtonElement :replace-class="{
  classname: {
    'from-class': 'to-class',
    'from-class': ['to-class'],
    'from-class': [{'to-class': true}],
  }
}" ... />

Replaces the classes of any class names of ButtonElement component. The keys are the original class names and the values are the replacements. The keys can only be single classes, while values can contain multiple ones in string or an array. When Vue style classes are used object values must be wrapped in an array.

Learn more about replacing classes here.

overrideClasses

  • Type: object
  • Default: {}
<ButtonElement :override-classes="{
  ComponentName: {
    classname: 'class-value',
    classname: ['class-value'],
    classname: [{'class-value': true}],
  }
}" ... />

Overrides the classes of any component's class names. The classes can have string or array values. When Vue style classes are used object values must be wrapped in an array.

Learn more about overriding classes here.

overrideClass

  • Type: array|object|string
  • Default: null
<ButtonElement :override-classes="{
  ComponentName: {
    classname: 'class-value',
    classname: ['class-value'],
    classname: [{'class-value': true}],
  }
}" ... />

Overrides the classes of any of ButtonElement component's class names. The classes can have string or array values. When Vue style classes are used object values must be wrapped in an array.

Learn more about overriding classes here.

templates

  • Type: object
  • Default: {}
<template>
  <div id="app">
    <Vueform>
      <ButtonElement :templates="{ ElementError }" ... />
    </Vueform>
  </div>
</template>

<script>
import { markRaw } from 'vue'
import CustomElementError from './CustomElementError.vue'

export default {
  data() {
    return {
      ElementError: markRaw(CustomElementError),
    }
  }
}
</script>

Overrides templates used by the component.

Learn more about overriding templates here.

presets

  • Type: array
  • Default: []
<ButtonElement :presets="['preset1', 'preset2']" ... />

The presets to be applied for the component.

Learn more about presets classes here.

slots

  • Type: object
  • Default: {}
<script>
import { Vueform, useVueform } from '@vueform/vueform'
import CustomDescriptionSlot from 'path/to/CustomDescriptionSlot.vue'

export default {
  mixins: [Vueform],
  setup: useVueform,
  data: () => ({
    vueform: {
      schema: {
        element: {
          type: 'button',
          slots: {
            label: '<span>Label</span>',
            description: CustomDescriptionSlot,
          }
        }
      }
    }
  })
}
</script>

With this option you can define slot values in a schema based form that you would normally just write inline. The value of a slot can be a plain string, HTML or a component with render function.

While this option can be also used in inline forms, it's primarily intended for schema based forms.

Properties

Properties include data, computed and inject properties of the component. You can use them by reaching the element's Vue component instance via form$'s el$(path) method or directly via this in options API or el$ in Composition API.

aria

  • Type: object
  • Group: computed

The aria-* attributes of the input.

path

  • Type: string
  • Group: computed

The path of the element using dot . syntax.

available

  • Type: boolean
  • Group: computed

Whether no conditions are defined or they are all fulfilled.

hidden

  • Type: boolean
  • Default: false
  • Group: data

Whether the element was hidden programmatically with show() or hide() methods.

visible

  • Type: boolean
  • Group: computed

Whether the element is visible. It's false when available or active is false or hidden is true.

isDisabled

  • Type: boolean
  • Group: computed

Whether the button is disabled.

isLoading

  • Type: boolean
  • Group: computed

Whether the button is in loading state.

fieldId

  • Type: string
  • Group: computed

The id of the button. If id is not provided path will be used.

hasLabel

  • Type: boolean
  • Group: computed

Whether the element has a label option, a #label slot or Vueform component's forceLabels option is true.

Size

  • Type: string
  • Group: computed

The resolved size of the element and all of its child components.

View

  • Type: string
  • Group: computed

The name of the resolved view for the component and the default view for its child components. Child component views can be overridden with views option. This one should be used to determine the component's view in class functions.

template

  • Type: object
  • Group: computed

The component's template.

classes

  • Type: object
  • Group: computed

The component's classes.

theme

  • Type: object
  • Group: inject

The global theme object, which contains all the default templates and classes.

form$

  • Type: component
  • Group: inject

The root form's component.

el$

  • Type: component
  • Group: computed

The element's component.

mounted

  • Type: boolean
  • Default: true
  • Group: data

Whether the element has been already mounted.

Methods

The methods of the component that you can use by reaching the element's Vue component instance via form$'s el$(path) method or directly via this in options API or el$ in Composition API.

.on(event, callback)

  • Arguments:
    • {string} event* - name of the event to listen for
    • {function} callback* - callback to run when the event is triggered
  • Returns: void

Adds a listener for an event.

.off(event)

  • Arguments:
    • {string} event* - name of the event to remove
  • Returns: void

Removes all listeners for an event.

.fire(args)

  • Arguments:
    • {any} args* - list of arguments to pass over to the event callback
  • Returns: void

Fires and emits an event.

.hide()

  • Returns: void

Hides the element.

.show()

  • Returns: void

Shows the element if it was hidden with hide() method.

Events

With events you can subscribe to different events broadcasted by the element. It can be used inline as regular Vue event listeners with @event format. In schema it can be used in PascalCase format prefixed with on (eg. onChange).

<template>
  <Vueform>
    <ButtonElement @{eventName}="handler" ... />
  </Vueform>
</template>
<script>
import { Vueform, useVueform } from '@vueform/vueform'

export default {
  mixins: [Vueform],
  setup: useVueform,
  data: () => ({
    vueform: {
      schema: {
        element: {
          type: 'button',
          on{EventName}() {
            // ...
          }
        }
      }
    }
  })
}
</script>

You can also use on(event, callback) method to subscribe to events.

@click

  • Params:
    • {component} form$ - the form's component
    • {component} el$ - the element's component
    • {Event} event - the click Event

Triggered when the button is clicked.

@beforeCreate

  • Params:
    • {component} el$ - the element's component

Triggered in beforeCreate hook.

@created

  • Params:
    • {component} el$ - the element's component

Triggered in created hook.

@beforeMount

  • Params:
    • {component} el$ - the element's component

Triggered in beforeMount hook.

@mounted

  • Params:
    • {component} el$ - the element's component

Triggered in mounted hook.

@beforeUpdate

  • Params:
    • {component} el$ - the element's component

Triggered in beforeUpdate hook.

@updated

  • Params:
    • {component} el$ - the element's component

Triggered in updated hook.

@beforeUnmount

  • Params:
    • {component} el$ - the element's component

Triggered in beforeUnmount (or beforeDestroy in Vue 2) hook.

@unmounted

  • Params:
    • {component} el$ - the element's component

Triggered in unmounted (or destroyed in Vue 2) hook.

Slots

Slots can be used inline or in slots option object when used in schema:

<template>
  <Vueform>
    <ButtonElement ... >
      <template #{slot-name}="scope">
        <!-- ... --->
      </template>
    </ButtonElement>
  </Vueform>
</template>
<script>
import { Vueform, useVueform } from '@vueform/vueform'

export default {
  mixins: [Vueform],
  setup: useVueform,
  data: () => ({
    vueform: {
      schema: {
        element: {
          type: 'button',
          slots: {
            {slotName}: // implementation
          }
        }
      }
    }
  })
}
</script>

#label

  • Scope:
    • {component} el$ - the element's component

Renders a label for the element in ElementLabel component.

#info

  • Scope:
    • {component} el$ - the element's component

Renders an info icon in ElementInfo component next the the element label. When the icon is hovered it shows the content of this slot. The element needs to have a label to render this.

#description

  • Scope:
    • {component} el$ - the element's component

Renders description for the element in ElementDescription component.

#before

  • Scope:
    • {component} el$ - the element's component

Renders an ElementText component before the button.

#between

  • Scope:
    • {component} el$ - the element's component

Renders an ElementText component after the button and before description.

#after

  • Scope:
    • {component} el$ - the element's component

Renders an ElementText component after the description and error.

#default

  • Scope:
    • {component} el$ - the element's component

Renders the button's label.

👋 Hire Vueform team for form customizations and development Learn more