QCascader 🪜

Cascade selection box. Try story

When to use

• When you need to select from a set of associated data set. Such as province/city/district, company level, things classification.

• When selecting from a large data set, with multi-stage classification separated for easy selection.

• Chooses cascade items in one float layer for better user experience.

Example

Default view:

Using in template:

<q-cascader
  v-model="modelValue"
  :options="options"
/>

Using in component instance:

  ...
  setup() {
    // options example
    const options = [
      {
        value: 'guide',
        label: 'Guide',
        children: [
          {
            value: 'disciplines',
            label: 'Disciplines',
            children: [
              {
                value: 'consistency',
                label: 'Consistency',
              },
            ]
          },
          {
            value: 'alone',
            label: 'Alone'
          }
        ]
      },
      {
        value: 'disabled resource',
        label: 'Disabled resource',
        disabled: true,
        children: [
          {
            value: 'some child',
            label: 'Some child'
          }
        ]
      },
      {
        value: 'resource',
        label: 'Resource'
      }
    ];

    const modelValue = ref(null);

    return {
      options,
      modelValue,
    };
  }
});

import type {
  QCascaderPropOptions,
  QCascaderPropModelValue
} from '@qvant/qui-max';

export default defineComponent({
  setup() {
    // options example
    const options: QCascaderPropOptions = [
      {
        value: 'guide',
        label: 'Guide',
        children: [
          {
            value: 'disciplines',
            label: 'Disciplines',
            children: [
              {
                value: 'consistency',
                label: 'Consistency'
              }
            ]
          },
          {
            value: 'alone',
            label: 'Alone'
          }
        ]
      },
      {
        value: 'disabled resource',
        label: 'Disabled resource',
        disabled: true,
        children: [
          {
            value: 'some child',
            label: 'Some child'
          }
        ]
      },
      {
        value: 'resource',
        label: 'Resource'
      }
    ];

    const modelValue: QCascaderPropModelValue = ref(null);

    return {
      options,
      modelValue
    };
  }
});

Props

options

• Type: Array
• Default: null

// import type from lib
import type { QCascaderPropOptions } from '@qvant/qui-max';

options MUST be an Array of Objects, each object MUST contain required fields:

• value - an option's value
• label - visible label

Optional fields:

• disabled - disable an option
• children - child options

// option's type
interface Option {
  value: number | string;
  label: string;
  disabled?: boolean;
  children?: Nullable<Option[]>;
}

modelValue

• Type: String, Number, Array
• Default: null

// import type from lib
import type { QCascaderPropModelValue } from '@qvant/qui-max';

// TS type
type QCascaderPropModelValue = Nullable<number | string | (number | string)[]>;

Use:

• String or Number for single value (multiple prop is false).
• Array for several values (multiple prop is true).

if you want to set modelValue in advance, make sure your value (or values) exists in options.

allLevelsShown

• Type Boolean
• Default: true

Whether all path to value in tags is shown.

Using in template:

<q-cascader
  v-model="modelValue"
  :options="options"
  :all-levels-shown="false"
/>

separator

• Type String
• Default: /

The separator symbol in the selected value.

Using in template:

<q-cascader
  v-model="modelValue"
  :options="options"
  separator=" | "
/>

multiple

• Type Boolean
• Default: false

Whether QCascader accepts multiple values. Pass array as modelValue.

<q-cascader
  v-model="modelValue"
  :options="options"
  multiple
/>

clearable

• Type Boolean
• Default: false

Whether QCascader is clearable.

<q-cascader
  v-model="modelValue"
  :options="options"
  clearable
/>

disabled

• Type Boolean
• Default: false

Whether QCascader is disabled.

<q-cascader
  v-model="modelValue"
  :options="options"
  disabled
/>

checkStrictly

• Type Boolean
• Default: false

Checks each value as independent. Use for selecting category as value instead of it's children.

<q-cascader
  v-model="modelValue"
  :options="options"
  check-strictly
/>

collapseTags

• Type Boolean
• Default: false
• Required props:
  • multiple="true"

Hide tags in counter.

<q-cascader
  v-model="modelValue"
  :options="options"
  collapse-tags
  multiple
/>

placeholder

• Type String
• Default: null

As native placeholder.

teleportTo

• Type String, HTMLElement
• Default: null

Specifies a target element where QCascader will be moved from original layout place. (has to be a valid query selector, or an HTMLElement).

<q-cascader
  v-model="modelValue"
  :options="options"
  teleport-to="body"
/>

Events

update:modelValue

Triggers when model updates.

change

Alias for update:modelValue.

dropdown-close

Triggers when dropdown closes.

dropdown-expand

Triggers when dropdown expands.

<q-cascader
  v-model="modelValue"
  :options="options"
  @update:modelValue="handleValueUpdate"
  @change="handleValueUpdate"
  @dropdown-close="handleDropdownClose"
  @dropdown-expand="handleDropdownExpand"
/>

  setup() {
    const handleValueUpdate = () => {
      ...
    }

    const handleDropdownClose = () => {
      ...
    }

    const handleDropdownExpand = () => {
      ...
    }

    return { handleValueUpdate, handleDropdownClose, handleDropdownExpand }
  }