Queso

Appearance

QuesoCheckboxMultiple ​

A multiple checkbox group component that supports multiple selections from a list of choices, two-way data binding with v-model, and provides a consistent interface for form inputs. All form field components share the same base structure for consistent styling and behavior across your application.

Basic Usage ​

vue
<template>
    <queso-checkbox-multiple
        name="interests"
        label="Interests"
        :choices="interestChoices"
        v-model="selectedInterests"
    />
</template>

<script setup>
import { ref } from "vue";
import { QuesoCheckboxMultiple } from "@allomambo/queso";

const selectedInterests = ref([]);
const interestChoices = [
    { label: "Technology", value: "tech" },
    { label: "Sports", value: "sports" },
    { label: "Music", value: "music" },
    { label: "Travel", value: "travel" },
];
</script>

Props ​

name ​

  • Type: string
  • Required: true
  • Description: The name attribute for the checkbox group field.

label ​

  • Type: string
  • Required: false
  • Description: The label text displayed above the checkbox group.

id ​

  • Type: string
  • Required: false
  • Description: The ID attribute for the checkbox group field (defaults to name if not provided).

choices ​

  • Type: QuesoCheckboxMultipleChoices<TChoiceData>
  • Required: true
  • Description: Array of choices for the checkbox group. Each choice must have a label and value, with optional data. TChoiceData defaults to Record<string, any> so you can strongly type additional metadata (icons, descriptions, etc.).

validationMessage ​

  • Type: string
  • Default: "Please select at least one option"
  • Description: Custom validation message when no options are selected and the field is required.

isRequired ​

  • Type: boolean
  • Default: false
  • Description: Whether the field is required.

isDisabled ​

  • Type: boolean
  • Default: false
  • Description: Whether the field is disabled.

isReadOnly ​

  • Type: boolean
  • Default: false
  • Description: Whether the field is read-only.

isError ​

  • Type: boolean
  • Default: false
  • Description: Whether the field has an error state.

extraAttributes ​

  • Type: Record<string, string>
  • Required: false
  • Description: Additional HTML attributes to apply to each checkbox input element.

Slots ​

beforeLabel ​

  • Props: ExposedData
  • Description: Content displayed before the label text.

label ​

  • Props: ExposedData
  • Description: The main label content. Defaults to the label prop if not provided.

required ​

  • Props: ExposedData
  • Description: Content displayed for the required indicator. Defaults to * if not provided.

afterLabel ​

  • Props: ExposedData
  • Description: Content displayed after the label text.

beforeInput ​

  • Props: ExposedData
  • Description: Content displayed before the checkbox group field.

checkbox ​

  • Props: ExposedData & QuesoCheckboxMultipleChoice<TChoiceData> & { isHovered: boolean, isSelected: boolean }
  • Description: Custom checkbox container element for each choice. Defaults to a styled checkbox container.

checkboxBox ​

  • Props: ExposedData & QuesoCheckboxMultipleChoice<TChoiceData> & { isHovered: boolean, isSelected: boolean }
  • Description: Custom checkbox box element for each choice. Defaults to a styled checkbox box.

checkboxBoxSymbol ​

  • Props: ExposedData & QuesoCheckboxMultipleChoice<TChoiceData> & { isHovered: boolean, isSelected: boolean }
  • Description: Symbol displayed inside the checkbox box when checked. Defaults to "✔︎".

checkboxLabel ​

  • Props: ExposedData & QuesoCheckboxMultipleChoice<TChoiceData> & { isHovered: boolean, isSelected: boolean }
  • Description: Custom label element for each choice. Defaults to the choice label.

afterInput ​

  • Props: ExposedData
  • Description: Content displayed after the checkbox group field.

error ​

  • Props: ExposedData
  • Description: Content displayed when the field has an error state.

Examples ​

Basic TypeScript Support ​

vue
<template>
    <queso-checkbox-multiple
        name="skills"
        label="Skills"
        :choices="skillChoices"
        v-model="selectedSkills"
    />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { QuesoCheckboxMultiple } from "@allomambo/queso";
import type {
    QuesoCheckboxMultipleModel,
    QuesoCheckboxMultipleChoices,
} from "@allomambo/queso";

const selectedSkills = ref<QuesoCheckboxMultipleModel>([]);
const skillChoices: QuesoCheckboxMultipleChoices = [
    { label: "JavaScript", value: "js" },
    { label: "TypeScript", value: "ts" },
    { label: "Vue.js", value: "vue" },
    { label: "React", value: "react" },
];
</script>
html
<div class="queso-field">
    <div class="queso-field__label">
        <span class="queso-field__label__text">Skills</span>
    </div>
    <div class="queso-field__input">
        <label class="queso-checkbox" for="skills-js">
            <span class="queso-checkbox__box">
                <span class="queso-checkbox__box__symbol">✔︎</span>
            </span>
            <span class="queso-checkbox__label">
                <span class="queso-checkbox__label__text">JavaScript</span>
            </span>
            <input
                class="queso-checkbox__native"
                type="checkbox"
                id="skills-js"
                name="skills[]"
                value="js"
            />
        </label>
        <label class="queso-checkbox" for="skills-ts">
            <span class="queso-checkbox__box">
                <span class="queso-checkbox__box__symbol">✔︎</span>
            </span>
            <span class="queso-checkbox__label">
                <span class="queso-checkbox__label__text">TypeScript</span>
            </span>
            <input
                class="queso-checkbox__native"
                type="checkbox"
                id="skills-ts"
                name="skills[]"
                value="ts"
            />
        </label>
        <label class="queso-checkbox" for="skills-vue">
            <span class="queso-checkbox__box">
                <span class="queso-checkbox__box__symbol">✔︎</span>
            </span>
            <span class="queso-checkbox__label">
                <span class="queso-checkbox__label__text">Vue.js</span>
            </span>
            <input
                class="queso-checkbox__native"
                type="checkbox"
                id="skills-vue"
                name="skills[]"
                value="vue"
            />
        </label>
        <label class="queso-checkbox" for="skills-react">
            <span class="queso-checkbox__box">
                <span class="queso-checkbox__box__symbol">✔︎</span>
            </span>
            <span class="queso-checkbox__label">
                <span class="queso-checkbox__label__text">React</span>
            </span>
            <input
                class="queso-checkbox__native"
                type="checkbox"
                id="skills-react"
                name="skills[]"
                value="react"
            />
        </label>
    </div>
</div>

With Validation ​

vue
<template>
    <queso-checkbox-multiple
        name="categories"
        label="Product Categories"
        :choices="categoryChoices"
        is-required
        validation-message="Please select at least one category"
        v-model="selectedCategories"
    />
</template>

<script setup>
import { ref } from "vue";
import { QuesoCheckboxMultiple } from "@allomambo/queso";

const selectedCategories = ref([]);
const categoryChoices = [
    { label: "Electronics", value: "electronics" },
    { label: "Clothing", value: "clothing" },
    { label: "Books", value: "books" },
    { label: "Home & Garden", value: "home" },
];
</script>
html
<div class="queso-field">
    <div class="queso-field__label">
        <span class="queso-field__label__text">Product Categories</span>
        <span class="queso-field__label__required">*</span>
    </div>
    <div class="queso-field__input">
        <label class="queso-checkbox" for="categories-electronics">
            <span class="queso-checkbox__box">
                <span class="queso-checkbox__box__symbol">✔︎</span>
            </span>
            <span class="queso-checkbox__label">
                <span class="queso-checkbox__label__text">Electronics</span>
            </span>
            <input
                class="queso-checkbox__native"
                type="checkbox"
                id="categories-electronics"
                name="categories[]"
                value="electronics"
                required
            />
        </label>
        <label class="queso-checkbox" for="categories-clothing">
            <span class="queso-checkbox__box">
                <span class="queso-checkbox__box__symbol">✔︎</span>
            </span>
            <span class="queso-checkbox__label">
                <span class="queso-checkbox__label__text">Clothing</span>
            </span>
            <input
                class="queso-checkbox__native"
                type="checkbox"
                id="categories-clothing"
                name="categories[]"
                value="clothing"
                required
            />
        </label>
        <label class="queso-checkbox" for="categories-books">
            <span class="queso-checkbox__box">
                <span class="queso-checkbox__box__symbol">✔︎</span>
            </span>
            <span class="queso-checkbox__label">
                <span class="queso-checkbox__label__text">Books</span>
            </span>
            <input
                class="queso-checkbox__native"
                type="checkbox"
                id="categories-books"
                name="categories[]"
                value="books"
                required
            />
        </label>
        <label class="queso-checkbox" for="categories-home">
            <span class="queso-checkbox__box">
                <span class="queso-checkbox__box__symbol">✔︎</span>
            </span>
            <span class="queso-checkbox__label">
                <span class="queso-checkbox__label__text">Home & Garden</span>
            </span>
            <input
                class="queso-checkbox__native"
                type="checkbox"
                id="categories-home"
                name="categories[]"
                value="home"
                required
            />
        </label>
    </div>
</div>

With Extra Attributes ​

vue
<template>
    <queso-checkbox-multiple
        name="permissions"
        label="User Permissions"
        :choices="permissionChoices"
        v-model="selectedPermissions"
        :extra-attributes="{
            'data-testid': 'permission-checkbox',
            'aria-describedby': 'permissions-help',
        }"
    />
    <div id="permissions-help" class="help-text">
        Select the permissions you want to grant to this user
    </div>
</template>

<script setup>
import { ref } from "vue";
import { QuesoCheckboxMultiple } from "@allomambo/queso";

const selectedPermissions = ref([]);
const permissionChoices = [
    { label: "Read", value: "read" },
    { label: "Write", value: "write" },
    { label: "Delete", value: "delete" },
    { label: "Admin", value: "admin" },
];
</script>
html
<div class="queso-field">
    <div class="queso-field__label">
        <span class="queso-field__label__text">User Permissions</span>
    </div>
    <div class="queso-field__input">
        <label class="queso-checkbox" for="permissions-read">
            <span class="queso-checkbox__box">
                <span class="queso-checkbox__box__symbol">✔︎</span>
            </span>
            <span class="queso-checkbox__label">
                <span class="queso-checkbox__label__text">Read</span>
            </span>
            <input
                class="queso-checkbox__native"
                type="checkbox"
                id="permissions-read"
                name="permissions[]"
                value="read"
                data-testid="permission-checkbox"
                aria-describedby="permissions-help"
            />
        </label>
        <label class="queso-checkbox" for="permissions-write">
            <span class="queso-checkbox__box">
                <span class="queso-checkbox__box__symbol">✔︎</span>
            </span>
            <span class="queso-checkbox__label">
                <span class="queso-checkbox__label__text">Write</span>
            </span>
            <input
                class="queso-checkbox__native"
                type="checkbox"
                id="permissions-write"
                name="permissions[]"
                value="write"
                data-testid="permission-checkbox"
                aria-describedby="permissions-help"
            />
        </label>
        <label class="queso-checkbox" for="permissions-delete">
            <span class="queso-checkbox__box">
                <span class="queso-checkbox__box__symbol">✔︎</span>
            </span>
            <span class="queso-checkbox__label">
                <span class="queso-checkbox__label__text">Delete</span>
            </span>
            <input
                class="queso-checkbox__native"
                type="checkbox"
                id="permissions-delete"
                name="permissions[]"
                value="delete"
                data-testid="permission-checkbox"
                aria-describedby="permissions-help"
            />
        </label>
        <label class="queso-checkbox" for="permissions-admin">
            <span class="queso-checkbox__box">
                <span class="queso-checkbox__box__symbol">✔︎</span>
            </span>
            <span class="queso-checkbox__label">
                <span class="queso-checkbox__label__text">Admin</span>
            </span>
            <input
                class="queso-checkbox__native"
                type="checkbox"
                id="permissions-admin"
                name="permissions[]"
                value="admin"
                data-testid="permission-checkbox"
                aria-describedby="permissions-help"
            />
        </label>
    </div>
</div>
<div id="permissions-help" class="help-text">
    Select the permissions you want to grant to this user
</div>

Read-only Field ​

vue
<template>
    <queso-checkbox-multiple
        name="roles"
        label="User Roles"
        :choices="roleChoices"
        is-read-only
        v-model="userRoles"
    />
</template>

<script setup>
import { ref } from "vue";
import { QuesoCheckboxMultiple } from "@allomambo/queso";

const userRoles = ref(["admin", "moderator"]);
const roleChoices = [
    { label: "User", value: "user" },
    { label: "Moderator", value: "moderator" },
    { label: "Admin", value: "admin" },
    { label: "Super Admin", value: "super-admin" },
];
</script>
html
<div class="queso-field is-read-only">
    <div class="queso-field__label">
        <span class="queso-field__label__text">User Roles</span>
    </div>
    <div class="queso-field__input">
        <div class="queso-checkbox">
            <span class="queso-checkbox__box">
                <span class="queso-checkbox__box__symbol">✔︎</span>
            </span>
            <span class="queso-checkbox__label">
                <span class="queso-checkbox__label__text">User</span>
            </span>
        </div>
        <div class="queso-checkbox is-checked">
            <span class="queso-checkbox__box">
                <span class="queso-checkbox__box__symbol">✔︎</span>
            </span>
            <span class="queso-checkbox__label">
                <span class="queso-checkbox__label__text">Moderator</span>
            </span>
        </div>
        <div class="queso-checkbox is-checked">
            <span class="queso-checkbox__box">
                <span class="queso-checkbox__box__symbol">✔︎</span>
            </span>
            <span class="queso-checkbox__label">
                <span class="queso-checkbox__label__text">Admin</span>
            </span>
        </div>
        <div class="queso-checkbox">
            <span class="queso-checkbox__box">
                <span class="queso-checkbox__box__symbol">✔︎</span>
            </span>
            <span class="queso-checkbox__label">
                <span class="queso-checkbox__label__text">Super Admin</span>
            </span>
        </div>
    </div>
</div>

Behavior ​

  • Two-way Data Binding: Uses Vue 3's defineModel for seamless v-model integration
  • Form Integration: Designed to work seamlessly with HTML forms
  • Multiple Selection: Multiple choices can be selected simultaneously
  • Read-only Mode: When is-read-only is true, displays the choices as non-interactive elements
  • Customizable Appearance: Slots for customizing checkbox box and label appearance
  • Validation: Built-in validation for required fields with custom validation messages

Accessibility ​

  • Label Association: Uses proper label element with for attribute
  • Required Indicator: Displays visual indicator for required fields
  • Error States: Provides clear error messaging and styling
  • Keyboard Navigation: Full keyboard accessibility support
  • Screen Reader Support: Proper ARIA attributes and semantic structure
  • State Management: Tracks hover and focus states for accessibility
  • Checkbox Group: Proper checkbox group semantics with array-based selection

CSS Classes ​

Field Container ​

  • .queso-field - Main field container
  • .queso-field.is-disabled - Disabled state
  • .queso-field.is-error - Error state
  • .queso-field.is-active - Focused state
  • .queso-field.is-hover - Hover state
  • .queso-field.is-read-only - Read-only state

Label ​

  • .queso-field__label - Label container
  • .queso-field__label__text - Label text
  • .queso-field__label__required - Required indicator

Checkbox Items ​

🎨

The styles for each individual checkbox come from the QuesoCheckbox component. See the CSS Classes section in QuesoCheckbox for detailed styling information.

Error ​

  • .queso-field__error - Error message container

Type Declaration ​

typescript
export interface ExposedData {
    fieldID: string;
    fieldName: string;
    isRequired: boolean;
    isDisabled: boolean;
    isReadOnly: boolean;
    isError: boolean;
    isActive: boolean;
    isHover: boolean;
}

export interface QuesoCheckboxMultipleChoice<
    TChoiceData = Record<string, any>,
> {
    label: string;
    value: string;
    isChecked?: boolean;
    data?: TChoiceData;
}

export type QuesoCheckboxMultipleChoices<TChoiceData = Record<string, any>> =
    QuesoCheckboxMultipleChoice<TChoiceData>[];
export type QuesoCheckboxMultipleModel = QuesoCheckboxMultipleChoice["value"][];

export interface QuesoCheckboxMultipleProps<TChoiceData = Record<string, any>> {
    name: string;
    label?: string;
    id?: string;
    choices: QuesoCheckboxMultipleChoices<TChoiceData>;
    validationMessage?: string;
    isRequired?: boolean;
    isDisabled?: boolean;
    isReadOnly?: boolean;
    isError?: boolean;
    extraAttributes?: Record<string, string>;
}

MamboMambo © 2024-present