A flexible alternative to the non existing but widely used "switch" type input

by Vue.js Examples

UiSwitch

The UiSwitch component is a flexible alternative to the non existing but widely used “switch” type input.

Features ✨

  • Vue 3
  • Fully accessible
  • Easily customisable with CSS
  • Familiar input element experience
  • Can be controlled or uncontrolled
  • Renders a visually hidden input element

Props ⚙

Name Type Default Description
modelValue Boolean undefined Used internally by v-model
tag String undefined This is the root tag that will be rendered. Mainly for semantics or core web functionality. Preferably a HTMLElement
id String button This is useful if you want to control the internal <input/> with another element, mostly a <label>
required Boolean undefined This is used if the UiSwitch will be used as a required field in a form
readonly Boolean undefined This is adds the readonly attribute the the internal <input/>
disabled Boolean undefined This is used to completely disable the UiSwitch
validate Function undefined Use this prop if you wish to validate the current value of an input. The function is expected to return a String of an error message which will be set on the internal <input/> or true if the current value is accepted
initial Boolean undefined This is used to set the initial state when no v-model is used
height [String, Number] undefined This is used to set the height of the root element. This prop basically sets a the --ui-height CSS variable on the style attribute
width [String, Number] undefined This is used to set the width of the root element. This prop basically sets a the --ui-width CSS variable on the style attribute

Structure ?

<slot name='prepend'/>
    
 <props.tag data-ui-switch='' class='root'>
    <div class='track'>
      <slot name='track'/>
    </div>
      
    <div class='thumb'>
      <input/>
      <slot name='thumb'/>
    </div>
 </props.tag> 
     
<slot name='append'/>

Slots ?

Name Payload Description
prepend 

{ 
  active: Boolean,
  validation: {
    message: '',
    valid: true
  },
  toggle: Function
}
Use this slot to render something else before the root component, commonly used for prepending a <label/>
track Same as prepend Use this slot to render anything inside the .track element
thumb Same as prepend Use this slot to render anything inside the .thumb element
default Same as prepend Use this slot to render anything inside the root element
append Same as prepend Use this slot to render something else after the root component, commonly used for appending a <label/>

All slots are optional, and can accept multiple elements

Examples ?‍♀️

Simplest form

<div id='app'>
 <UiSwitch/>
</div>

With v-model

<div id='app'>
 <UiSwitch v-model='switch'/>
</div>

With an external <label>

<div id='app'>
 <label for='switch'>
  Toggle UiSwitch
 </label>
 
 <UiSwitch id='switch' v-model='switch'/>
</div>

With an internal <label> (prepend) and an internal validation message <span> (append)

<div id='app'>
 <UiSwitch id='switch'>
  <template v-slot:prepend='{active}'>
    <label for='switch'>
     Selected: {{active}}
    </label>  
  </template>
  
  <template v-slot:append='{validation, toggle}'>
    <span v-if='validation.message' @click='toggle'>
     Error!
    </span>
  </template>
 </UiSwitch>
</div>

CSS variables

Name Default value Description
–ui-height 28px Use this variable to set the root element’s height
–ui-width 44px Use this variable to set the root element’s width
–ui-track-height 100% Sets the height of the track
–ui-track-radius 100% Sets the border-radius of the track
–ui-track-background #999 Sets the background of the track
–ui-track-background-checked #007bff Sets the background of the track when the component is active
–ui-thumb-size 25px Sets the height and width of the .thumb element
–ui-thumb-radius 50% Sets the border-radius of the .thumb element
–ui-thumb-offset 1.5px The gap between the thumb and the edges
–ui-thumb-translatex 

calc(var(--ui-width) - 
   var(--ui-thumb-size) - 
   var(--ui-thumb-offset)
)
 Computes the active state transformation
–ui-thumb-background #fff The background of the thumb

GitHub

View Github