Components
    Show · Collapse

    Collapse

    Display content areas can be expanded or folded.

    Demos

    How to import

    <script setup lang="ts">
    import { Collapse } from '@fibrous/semi-ui-vue';
</script>

    Collapse.Panel can also be imported by name as CollapsePanel. The header and extra of a Panel are slots (#header, #extra). A Panel can only be used inside Collapse, otherwise it throws a descriptive error.

    Basic Usage

    You can expand multiple panels at the same time, and use defaultActiveKey to set the panel to expand by default.

    Code
    <script setup lang="ts">
    import { Collapse } from '@fibrous/semi-ui-vue';
</script>

<template>
    <Collapse>
        <Collapse.Panel itemKey="1">
            <template #header>This is panel header 1</template>
            <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
        </Collapse.Panel>
        <Collapse.Panel itemKey="2">
            <template #header>This is panel header 2</template>
            <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
        </Collapse.Panel>
        <Collapse.Panel itemKey="3">
            <template #header>This is panel header 3</template>
            <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
        </Collapse.Panel>
    </Collapse>
</template>

    Accordion

    Use accordion to restrict one panel only to be expanded at one time.

    Code
    <script setup lang="ts">
    import { Collapse } from '@fibrous/semi-ui-vue';
</script>

<template>
    <Collapse accordion>
        <Collapse.Panel itemKey="1">
            <template #header>This is panel header 1</template>
            <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
        </Collapse.Panel>
        <Collapse.Panel itemKey="2">
            <template #header>This is panel header 2</template>
            <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
        </Collapse.Panel>
        <Collapse.Panel itemKey="3">
            <template #header>This is panel header 3</template>
            <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
        </Collapse.Panel>
    </Collapse>
</template>

    Disable Panel

    Use disabled to disabled panel.

    Code
    <script setup lang="ts">
    import { Collapse } from '@fibrous/semi-ui-vue';
</script>

<template>
    <Collapse accordion>
        <Collapse.Panel disabled itemKey="1">
            <template #header>This is panel header 1</template>
            <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
        </Collapse.Panel>
        <Collapse.Panel itemKey="2">
            <template #header>This is panel header 2</template>
            <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
        </Collapse.Panel>
        <Collapse.Panel itemKey="3">
            <template #header>This is panel header 3</template>
            <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
        </Collapse.Panel>
    </Collapse>
</template>

    Hide The Panel Icon

    Use showArrow to hide the panel icon.

    Code
    <script setup lang="ts">
    import { Collapse } from '@fibrous/semi-ui-vue';
</script>

<template>
    <Collapse accordion>
        <Collapse.Panel itemKey="1" :showArrow="false">
            <template #header>This is panel header 1</template>
            <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
        </Collapse.Panel>
        <Collapse.Panel itemKey="2">
            <template #header>This is panel header 2</template>
            <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
        </Collapse.Panel>
        <Collapse.Panel itemKey="3">
            <template #header>This is panel header 3</template>
            <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
        </Collapse.Panel>
    </Collapse>
</template>

    Custom Icon

    Use the #expandIcon slot of Collapse to set the expanding icon and the #collapseIcon slot for the folded icon. A slot that is present but empty shows no icon. Known limitation: when the caller adds or removes a whole one of these slots with v-if, a panel may keep the old icon.

    The expanding icon is shown while a panel is collapsed (it can be expanded), the folded icon while it is expanded.

    Code
    <script setup lang="ts">
    import { IconMinus, IconPlus } from '@fibrous/semi-icons-vue';
    import { Collapse } from '@fibrous/semi-ui-vue';
</script>

<template>
    <Collapse>
        <template #expandIcon>
            <IconPlus />
        </template>
        <template #collapseIcon>
            <IconMinus />
        </template>
        <Collapse.Panel itemKey="1">
            <template #header>This is panel header 1</template>
            <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
        </Collapse.Panel>
        <Collapse.Panel itemKey="2">
            <template #header>This is panel header 2</template>
            <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
        </Collapse.Panel>
        <Collapse.Panel itemKey="3">
            <template #header>This is panel header 3</template>
            <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
        </Collapse.Panel>
    </Collapse>
</template>

    Custom Extra Content on the Right-upper Corner

    Use the #extra slot to set extra content on the right-upper corner.

    #header is rendered inside the panel's toggle button, so it may only hold text, icons and other non-interactive content. #extra sits beside the button in the same row and may hold controls such as buttons or inputs.

    1234
    Recommended
    Code
    <script setup lang="ts">
    import { IconCopy } from '@fibrous/semi-icons-vue';
    import { Collapse, Tag } from '@fibrous/semi-ui-vue';
</script>

<template>
    <Collapse>
        <Collapse.Panel itemKey="1">
            <template #header>This is panel header 1</template>
            <template #extra>1234</template>
            <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
        </Collapse.Panel>
        <Collapse.Panel itemKey="2">
            <template #header>This is panel header 2</template>
            <template #extra>
                <IconCopy />
            </template>
            <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
        </Collapse.Panel>
        <Collapse.Panel itemKey="3">
            <template #header>This is panel header 3</template>
            <template #extra>
                <Tag color="violet" :style="{ margin: 0 }">Recommended</Tag>
            </template>
            <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
        </Collapse.Panel>
    </Collapse>
</template>

    API reference

    Collapse

    Props

    PropertyDescriptionTypeDefault
    activeKeyControlled property, key of the currently expanded panel; null and the empty string mean all panels are collapsed.string | string[] | nullundefined
    defaultActiveKeyKey of the panel expanded initially.string | string[]semiDefault("Collapse", "defaultActiveKey", "")
    accordionAccordion mode.booleansemiGlobalDefault("Collapse", "accordion")
    clickHeaderToExpandClicking anywhere in the header row toggles the panel; when false only the toggle button and the arrow respond.booleansemiDefault("Collapse", "clickHeaderToExpand", true)
    expandIconPositionPosition of the expand icon: left or right."left" | "right"semiDefault("Collapse", "expandIconPosition", "right")
    keepDOMWhether to keep the DOM tree of hidden panels; destroyed by default. When omitted it reads the global default of Collapse, then that of Collapsible.booleansemiGlobalDefault("Collapse", "keepDOM")
    motionWhether to enable the animation; enabled by default. When omitted it reads the global default of Collapse, then that of Collapsible.booleansemiGlobalDefault("Collapse", "motion")
    lazyRenderUsed with keepDOM; when true, panel content is not rendered until the panel is first expanded.booleansemiDefault("Collapse", "lazyRender", false)

    Events

    EventDescriptionCallback parameters
    update:activeKeyEmitted when the expanded panels change, always with a string[]; used by v-model:activeKey.[activeKey: string[]]
    changeEmitted when a panel is toggled, with the array of expanded keys and the native MouseEvent (keyboard use also produces a click through the native button).[activeKey: string[], event: MouseEvent]

    Slots

    SlotDescriptionScope parameters
    defaultCollapse.Panel panels.any
    expandIconIcon shown while a panel is collapsed, IconChevronDown by default; empty content shows no icon.any
    collapseIconIcon shown while a panel is expanded, IconChevronUp by default; empty content shows no icon.any

    Exposes

    NameDescriptionType
    None

    class, style and native attributes are passed through attrs and land on the root element of Collapse. The activeKey of update:activeKey and change is always a string[]: when the initial value of v-model:activeKey is a string, it becomes an array after the first change.

    Collapse.Panel

    Props

    PropertyDescriptionTypeDefault
    itemKeyRequired and unique, matched against activeKey and defaultActiveKey.stringundefined
    showArrowWhether to show the arrow icon.booleantrue
    disabledWhether the panel is disabled.booleanfalse

    Events

    EventDescriptionCallback parameters
    motionEndEmitted when the expand or collapse animation ends.[]

    Slots

    SlotDescriptionScope parameters
    defaultPanel content.any
    headerPanel header content, rendered inside the toggle button; must not contain interactive elements.any
    extraAuxiliary content on the right of the panel header, outside the toggle button; may hold controls.any

    Exposes

    NameDescriptionType
    None

    class, style and native attributes are passed through attrs and land on the root element of the Panel (.semi-collapse-item). Panel does not read global defaults.

    Accessibility

    ARIA

    • Each panel header follows the WAI-ARIA Accordion pattern: a native button wrapped in an element with role="heading" and aria-level="3". The button's accessible name is the header content.
    • The button carries aria-expanded, and aria-controls pointing at the panel content whenever that content is still in the DOM: always when open, and when closed once keepDOM is in effect (including when keepDOM is only set in the global defaults of Collapsible) and the content has been rendered, for example a panel opened once and closed again with keepDOM and lazyRender. A closed panel that lazyRender has not rendered yet has no content and no aria-controls.
    • The panel content has role="region" and is labelled by the button through aria-labelledby; closed content kept by keepDOM is inert.
    • The expand icon is decorative and has aria-hidden="true"; extra is outside the button.
    • A disabled panel uses the button's native disabled attribute.

    Keyboard and Focus

    • Each panel header button is one Tab stop; disabled panels are skipped.
    • Enter or Space on the focused button expands or collapses the panel, also when clickHeaderToExpand is false.
    • Controls inside extra are Tab stops of their own.

    Content Guidelines

    The essence of the folding panel is that the card container adds the function of folding and unfolding, so the copywriting specification of the folding panel needs to be the same as the Card copywriting specification

    Design Tokens

    These are the component's internal Sass variables and cannot be overridden. To customize styles, override the --semi-* CSS variables (see the Design Token page) or write unlayered CSS rules.
    Sass variableValueUsage
    $color-collapse_item-border-defaultvar(--semi-color-border)分割线颜色
    $color-collapse_header-text-defaultvar(--semi-color-text-0)标题文字颜色
    $color-collapse_header-text-disabledvar(--semi-color-disabled-text)标题文字颜色 禁用
    $color-collapse_header-icon-defaultvar(--semi-color-text-2)展开箭头图标颜色
    $color-collapse_header-bg-hovervar(--semi-color-fill-0)菜单项背景颜色 - 悬浮
    $color-collapse_header-bg-activevar(--semi-color-fill-1)菜单项背景颜色 - 按下
    $color-collapse_content-text-defaultvar(--semi-color-text-1)内容文字颜色
    $font-collapse_header-fontWeight$font-weight-bold标题字重
    $spacing-collapse_header-marginX$spacing-tight标题水平外边距
    $spacing-collapse_header-marginY$spacing-extra-tight标题垂直外边距
    $spacing-collapse_header-padding$spacing-tight标题内边距
    $spacing-collapse_right-paddingRight$spacing-tight图标右侧内边距
    $spacing-collapse_header_iconLeft-marginRight8px
    $spacing-collapse_content-paddingTop$spacing-extra-tight内容顶部内边距
    $spacing-collapse_content-paddingRight$spacing-base内容右侧内边距
    $spacing-collapse_content-paddingBottom$spacing-tight内容底部内边距
    $spacing-collapse_content-paddingLeft$spacing-base内容左侧内边距
    $radius-collapse_headervar(--semi-border-radius-small)内容圆角大小
    $width-collapse_item-border1px分割线宽度
    $size-collapse_icon-default$width-icon-medium图标尺寸

    FAQ

    • Why is the data in Form cleared when using Collapse?

      When Collapse is collapsed, the related DOM is destroyed and so are the fields data stored in Form. You could set keepDOM of Collapse to true to keep the DOM from being destroyed.

    • The whole header row is a click hot zone for folding and expanding. If a control (such as Input) is placed in the row, clicking it collapses/expands the panel. How to avoid it?

      Put the control in extra, not in header: header is inside the toggle button and must not contain controls. With clickHeaderToExpand set to false only the toggle button and the icon respond to clicks; otherwise stop the click from bubbling to the header row in the control's click handler, or in a wrapping element's click handler if the control does not provide the event object, as in the example below.

    <script setup lang="ts">
    import { Collapse, Input } from '@fibrous/semi-ui-vue';
</script>

<template>
    <Collapse>
        <Collapse.Panel itemKey="1">
            <template #header>Panel header</template>
            <template #extra>
                <span @click.stop>
                    <Input aria-label="Panel note" />
                </span>
            </template>
            <p>Hi, bytedance dance dance. This is the docsite of Semi UI.</p>
        </Collapse.Panel>
    </Collapse>
</template>