Components

SelectableCardField

A form field that allows users to select an option by clicking on a card, often used in surveys, quizzes, or preference settings.

Component

View code

Show playground

Label (optional)

Option 1

Description for option 1

Option 2

Description for option 2

Option 3

Description for option 3

Help text example

Props

Props	Required	Default	Type
`id`	`true`	—	`string`
`label`	—	—	`string`
`options`	—	—	`SelectableCardOption[]`
`modelValue`	`true`	—	`string \| boolean \| Array<string \| boolean> \| null`
`multiple`	—	`false`	`boolean`
`selectMode`	—	`CardSelectionMode.CARD`	`CardSelectionMode`
`validator`	—	`null`	`function`
`error`	—	`''`	`string`
`required`	—	`false`	`boolean`
`showOptionalLabel`	—	`true`	`boolean`
`optionalLabel`	—	—	`string`
`disabled`	—	`false`	`boolean`
`helpText`	—	—	`string`
`helpTextPosition`	—	`Position.BOTTOM`	`Position`
`showLoadingState`	—	`false`	`boolean`
`isLoading`	—	`false`	`boolean`
`loadingText`	—	`'Loading'`	`string`
`titleClass`	—	—	`string`
`descriptionClass`	—	—	`string`
`checkIcon`	—	`'mdi:check-circle-outline'`	`string`
`containedIconShape`	—	`IconContainerShape.SQUARE`	`IconContainerShape`
`containedIconStyleType`	—	`IconContainerStyleType.FLAT`	`IconContainerStyleType`
`layoutAlign`	—	`Align.LEFT`	`Align`
`buttonSize`	—	`ButtonSize.LG`	`ButtonSize`
`hasSecondaryBtn`	—	`true`	`boolean`
`secondaryBtnText`	—	`'Details'`	`string`
`secondaryBtnStyleType`	—	`ButtonStyleType.NEUTRAL_OUTLINED`	`ButtonStyleType`
`secondaryBtnIconPosition`	—	`IconPosition.NONE`	`IconPosition`
`secondaryBtnIcon`	—	`'mdi:arrow-right'`	`string`
`selectBtnStyleType`	—	`ButtonStyleType.NEUTRAL_FILLED`	`ButtonStyleType`
`selectBtnIconPosition`	—	`IconPosition.NONE`	`IconPosition`
`selectBtnIcon`	—	`'mdi:arrow-right'`	`string`
`selectText`	—	`'Select'`	`string`
`selectedText`	—	`'Selected'`	`string`
`hasFooter`	—	`true`	`boolean`
`footerContentAlign`	—	`Align.RIGHT`	`Align`
`hasShadow`	—	`true`	`boolean`
`gridDesktopCols`	—	`3`	`number`
`gridTabletCols`	—	`2`	`number`
`gridMobileCols`	—	`1`	`number`

Usage

id

Sets the id of the field.

 <template>
  <SelectableCardField id="selectable-card-field-1" />
</template>

Type: string
Required: true

label

Sets the label of the field.

 <template>
  <SelectableCardField label="Label" />
</template>

Type: string

options

Sets the selectable card options.

 <template>
    <SelectableCardField :options="options" />
</template>
<script setup lang="ts">
const options = ref<SelectableCardOption[]>([
    {
        value: 'option1',
        title: 'Option 1',
        description: 'Description for option 1',
        icon: 'mdi:star-outline',
    },
    {
        value: 'option2',
        title: 'Option 2',
        description: 'Description for option 2',
        icon: 'mdi:help',   
    },
])
</script>

TypeScript interface

 export interface SelectableCardOption {
    value: string | boolean
    title: string
    titleClass?: string
    description: string
    descriptionClass?: string
    checkIcon?: string
    icon?: string
    containedIconColor?: ColorAccent
    hasSecondaryBtn?: boolean
    secondaryBtnText?: string
    secondaryBtnIconPosition?: IconPosition
    secondaryBtnIcon?: string
    disabled?: boolean
    secondaryBtnCallback?: () => void
}

modelValue

Sets the selected value (single) or values (multiple).

 <template>
    <SelectableCardField v-model="selected" />
</template>
<script setup lang="ts">
const selected = ref<string | null>(null)
</script>

For multi-select:

 <template>
    <SelectableCardField v-model="selected" multiple />
</template>
<script setup lang="ts">
const selected = ref<Array<string | boolean>>([])
</script>

Type: string | boolean | Array<string | boolean> | null
Required: true

multiple

Enables multiple selections.

 <template>
    <SelectableCardField multiple />
</template>

Type: boolean
Default: false

selectMode

Controls the selection UI behavior (card or button). It uses the CardSelectionMode enum for options.

 <template>
    <SelectableCardField :selectMode="CardSelectionMode.CARD" />
</template>

Type: CardSelectionMode
Default: CardSelectionMode.CARD

Options

Value	Description
`CARD`	Select by clicking the card
`BUTTON`	Select using the footer button

validator

Sets the validator function for the field, which controls its internal validation state.

It uses the validateField or validateArrayField utility to perform required field validation.

 <template>
    <SelectableCardField 
        :validator="validateField" 
        required 
    />
</template>

Type: function
Default: null

error (v-model:error)

Defines the error message displayed by the field. This prop is bindable via v-model:error.

 <template>
    <SelectableCardField v-model:error="errorMessage" />
</template>
<script setup lang="ts">
const errorMessage = ref('')
</script>

Type: string
Default: ''

required

Marks the field as required for validation.

 <template>
    <SelectableCardField required />
</template>

Type: boolean
Default: false

showOptionalLabel

When the field is not required, shows an "(optional)" hint next to the label. Set to false to hide it. The hint text defaults to a global setting that can be overridden project-wide, and can also be overridden per field with the optionalLabel prop.

 <template>
    <SelectableCardField label="Plan" :showOptionalLabel="false" />
</template>

Type: boolean
Default: true

optionalLabel

Overrides the "(optional)" hint text for this specific field, taking priority over the global default.

 <template>
    <SelectableCardField label="Plan" optionalLabel="(not required)" />
</template>

Type: string

disabled

Disables all options in the field.

 <template>
    <SelectableCardField disabled />
</template>

Type: boolean
Default: false

helpText

Sets the help text.

 <template>
    <SelectableCardField helpText="Help text example" />
</template>

Type: string

helpTextPosition

Sets the position of the help text relative to the field. It uses the Position enum.

 <template>
    <SelectableCardField helpTextPosition="top" helpText="Appears above the field" />
</template>

Type: Position
Default: Position.BOTTOM

Options

Value	Description
`TOP`	top
`BOTTOM`	bottom

showLoadingState

Toggles the loading state of the field.

 <template>
    <SelectableCardField :showLoadingState="true" :isLoading="true" />
</template>

Type: boolean
Default: false

isLoading

Sets the loading state of the field.

 <template>
    <SelectableCardField :isLoading="true" :showLoadingState="true" />
</template>

Type: boolean
Default: false

loadingText

Sets the loading text displayed when isLoading is true.

 <template>
    <SelectableCardField 
        :isLoading="true" 
        :showLoadingState="true" 
        loadingText="Loading"
    />
</template>

Type: string
Default: 'Loading'

titleClass

Adds a custom class to the option title.

 <template>
    <SelectableCardField titleClass="text-text-primary" />
</template>

Type: string

descriptionClass

Adds a custom class to the option description.

 <template>
    <SelectableCardField descriptionClass="text-text-neutral" />
</template>

Type: string

checkIcon

Sets the icon used for the selected state.

 <template>
    <SelectableCardField checkIcon="mdi:check" />
</template>

Type: string
Default: 'mdi:check-circle-outline'

containedIconShape

Sets the icon container shape. It uses the IconContainerShape enum for options.

 <template>
    <SelectableCardField :containedIconShape="IconContainerShape.CIRCLE" />
</template>

Type: IconContainerShape
Default: IconContainerShape.SQUARE

Options

Value	Description
`SQUARE`	square
`CIRCLE`	circle

containedIconStyleType

Sets the icon container style. It uses the IconContainerStyleType enum for options.

 <template>
    <SelectableCardField :containedIconStyleType="IconContainerStyleType.FILLED" />
</template>

Type: IconContainerStyleType
Default: IconContainerStyleType.FLAT

Options

Value	Description
`FLAT`	flat
`FILLED`	filled

layoutAlign

Sets the alignment of content inside each card. It uses the Align enum for options.

 <template>
    <SelectableCardField :layoutAlign="Align.CENTER" />
</template>

Type: Align
Default: Align.LEFT

Options

Value	Description
`LEFT`	left
`CENTER`	center

buttonSize

Sets the button size for footer actions. It uses the ButtonSize enum for options.

 <template>
    <SelectableCardField :buttonSize="ButtonSize.MD" />
</template>

Type: ButtonSize
Default: ButtonSize.LG

Options

Value	Description
`XXL`	2xl
`XL`	xl
`LG`	lg
`MD`	md
`SM`	sm
`XS`	xs

hasSecondaryBtn

Shows a secondary action button on each card.

 <template>
    <SelectableCardField :hasSecondaryBtn="false" />
</template>

Type: boolean
Default: true

secondaryBtnText

Sets the secondary button label.

 <template>
    <SelectableCardField secondaryBtnText="Details" />
</template>

Type: string
Default: 'Details'

secondaryBtnStyleType

Sets the secondary button style. It uses the ButtonStyleType enum for options.

 <template>
    <SelectableCardField :secondaryBtnStyleType="ButtonStyleType.NEUTRAL_OUTLINED" />
</template>

Type: ButtonStyleType
Default: ButtonStyleType.NEUTRAL_OUTLINED

Options

Value	Description
`PRIMARY_BRAND_FILLED`	primary-brand-filled
`PRIMARY_BRAND_TRANSPARENT`	primary-brand-transparent
`PRIMARY_BRAND_SOFT`	primary-brand-soft
`SECONDARY_BRAND_FILLED`	secondary-brand-filled
`NEUTRAL_OUTLINED`	neutral-outlined
`NEUTRAL_TRANSPARENT`	neutral-transparent
`NEUTRAL_TRANSPARENT_SUBTLE`	neutral-transparent-subtle
`NEUTRAL_FILLED`	neutral-filled
`DELETE_FILLED`	delete-filled
`DELETE_OUTLINED`	delete-outlined
`DELETE_SOFT`	delete-soft
`DELETE_TRANSPARENT`	delete-transparent

secondaryBtnIconPosition

Sets the icon position for the secondary button. It uses the IconPosition enum for options.

 <template>
    <SelectableCardField :secondaryBtnIconPosition="IconPosition.LEFT" />
</template>

Type: IconPosition
Default: IconPosition.NONE

Options

Value	Description
`NONE`	none
`LEFT`	left
`RIGHT`	right

secondaryBtnIcon

Sets the icon for the secondary button.

 <template>
    <SelectableCardField secondaryBtnIcon="mdi:arrow-right" />
</template>

Type: string
Default: 'mdi:arrow-right'

selectBtnStyleType

Sets the primary select button style. It uses the ButtonStyleType enum for options.

 <template>
    <SelectableCardField :selectBtnStyleType="ButtonStyleType.NEUTRAL_FILLED" />
</template>

Type: ButtonStyleType
Default: ButtonStyleType.NEUTRAL_FILLED

Options

Value	Description
`PRIMARY_BRAND_FILLED`	primary-brand-filled
`PRIMARY_BRAND_TRANSPARENT`	primary-brand-transparent
`PRIMARY_BRAND_SOFT`	primary-brand-soft
`SECONDARY_BRAND_FILLED`	secondary-brand-filled
`NEUTRAL_OUTLINED`	neutral-outlined
`NEUTRAL_TRANSPARENT`	neutral-transparent
`NEUTRAL_TRANSPARENT_SUBTLE`	neutral-transparent-subtle
`NEUTRAL_FILLED`	neutral-filled
`DELETE_FILLED`	delete-filled
`DELETE_OUTLINED`	delete-outlined
`DELETE_SOFT`	delete-soft
`DELETE_TRANSPARENT`	delete-transparent

selectBtnIconPosition

Sets the icon position for the select button. It uses the IconPosition enum for options.

 <template>
    <SelectableCardField :selectBtnIconPosition="IconPosition.RIGHT" />
</template>

Type: IconPosition
Default: IconPosition.NONE

Options

Value	Description
`NONE`	none
`LEFT`	left
`RIGHT`	right

selectBtnIcon

Sets the icon for the select button.

 <template>
    <SelectableCardField selectBtnIcon="mdi:arrow-right" />
</template>

Type: string
Default: 'mdi:arrow-right'

selectText

Sets the label for the unselected button state.

 <template>
  <SelectableCardField selectText="Select" />
</template>

Type: string
Default: 'Select'

selectedText

Sets the label for the selected button state.

 <template>
  <SelectableCardField selectedText="Selected" />
</template>

Type: string
Default: 'Selected'

hasFooter

Shows or hides the footer area of cards.

Important

When using the select mode `CardSelectionMode.BUTTON`, the footer will always be shown even if this prop is set to false, as the select button is located in the footer.

 <template>
    <SelectableCardField :hasFooter="false" />
</template>

Type: boolean
Default: true

footerContentAlign

Sets the footer content alignment.

 <template>
    <SelectableCardField :footerContentAlign="Align.RIGHT" />
</template>

Type: Align
Default: Align.RIGHT

Options

Value	Description
`LEFT`	left
`CENTER`	center
`RIGHT`	right

hasShadow

Toggles card shadow.

 <template>
    <SelectableCardField :hasShadow="false" />
</template>

Type: boolean
Default: true

gridDesktopCols

Sets the number of columns on desktop.

 <template>
    <SelectableCardField :gridDesktopCols="3" />
</template>

Type: number
Default: 3

gridTabletCols

Sets the number of columns on tablet.

 <template>
    <SelectableCardField :gridTabletCols="2" />
</template>

Type: number
Default: 2

gridMobileCols

Sets the number of columns on mobile.

 <template>
    <SelectableCardField :gridMobileCols="1" />
</template>

Type: number
Default: 1

gridGapClass

Sets the gap class for the grid layout.

 <template>
    <SelectableCardField :gridGapClass="'gap-6'" />
</template>

Type: string
Default: 'gap-6'