Collapsible - Semi Design Next

When to use

Collapsibleis a behavior component with animation effect by default. It is used in various components in Semi Components, including: Navigation, Collapse, Tree, TreeSelect, and Typography.
When the above components do not meet requirements or customized collapsed behavior, you can use Collapsible to put in contents that need to be expanded or folded.

Demos

How to import

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

Basic Usage

Use isOpen to control the expansion or folding of the content.

Code

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

    const isOpen = ref(false);
    const toggle = () => {
        isOpen.value = !isOpen.value;
    };
</script>

<template>
    <div>
        <Button aria-controls="collapsible-basic" :aria-expanded="isOpen" @click="toggle">Toggle</Button>
        <Collapsible id="collapsible-basic" :isOpen="isOpen">
            <ul>
                <li>
                    <p>Semi Design 以内容优先进行设计。</p>
                </li>
                <li>
                    <p>更容易地自定义主题。</p>
                </li>
                <li>
                    <p>适用国际化场景。</p>
                </li>
                <li>
                    <p>效率场景加入人性化关怀。</p>
                </li>
            </ul>
        </Collapsible>
    </div>
</template>

Custom Animation Duration

You can use duration to set animation duration or turn off animation by setting motion to false.

设置动画时间：

Code

<script setup lang="ts">
    import { ref } from 'vue';
    import { Button, Collapsible, InputNumber } from '@fibrous/semi-ui-vue';

    const isOpen = ref(false);
    const duration = ref(250);
    const toggle = () => {
        isOpen.value = !isOpen.value;
    };
    const setDuration = (value: number | string) => {
        duration.value = Number(value);
    };
</script>

<template>
    <div>
        <span id="collapsible-duration-label">设置动画时间：</span>
        <InputNumber aria-labelledby="collapsible-duration-label" :defaultValue="250" :min="0" :step="10" :style="{ width: '120px' }" @change="setDuration" />
        <br />
        <Button aria-controls="collapsible-duration" :aria-expanded="isOpen" @click="toggle">Toggle</Button>
        <Collapsible id="collapsible-duration" :duration="duration" :isOpen="isOpen">
            <ul>
                <li>
                    <p>Semi Design 以内容优先进行设计。</p>
                </li>
                <li>
                    <p>更容易地自定义主题。</p>
                </li>
                <li>
                    <p>适用国际化场景。</p>
                </li>
                <li>
                    <p>效率场景加入人性化关怀。</p>
                </li>
            </ul>
        </Collapsible>
    </div>
</template>

Nested use

Code

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

    const isOpen = ref(false);
    const isChildOpen = ref(false);
</script>

<template>
    <div>
        <Button aria-controls="collapsible-nested" :aria-expanded="isOpen" @click="isOpen = !isOpen">Toggle</Button>
        <br />
        <Collapsible id="collapsible-nested" :isOpen="isOpen">
            <div>
                <span>Semi Design的设计原则包括：</span>
                <Button aria-controls="collapsible-nested-list" :aria-expanded="isChildOpen" @click="isChildOpen = !isChildOpen"> Toggle List </Button>
            </div>
            <Collapsible id="collapsible-nested-list" :isOpen="isChildOpen">
                <ul>
                    <li>
                        <p>Semi Design 以内容优先进行设计。</p>
                    </li>
                    <li>
                        <p>更容易地自定义主题。</p>
                    </li>
                    <li>
                        <p>适用国际化场景。</p>
                    </li>
                    <li>
                        <p>效率场景加入人性化关怀。</p>
                    </li>
                </ul>
            </Collapsible>
        </Collapsible>
    </div>
</template>

Custom CollapseHeight

You could use collapseHeight to customize collapsed height.

Semi Design 以内容优先进行设计。
更容易地自定义主题。
适用国际化场景。
效率场景加入人性化关怀。

Code

<script setup lang="ts">
    import { computed, ref } from 'vue';
    import { Button, Collapsible } from '@fibrous/semi-ui-vue';

    const isOpen = ref(false);
    const maskStyle = computed(() =>
        isOpen.value
            ? {}
            : {
                  WebkitMaskImage: 'linear-gradient(to bottom, black 0%, rgba(0, 0, 0, 1) 60%, rgba(0, 0, 0, 0.2) 80%, transparent 100%)',
              }
    );
    const toggle = () => {
        isOpen.value = !isOpen.value;
    };
    const linkStyle = {
        position: 'absolute',
        left: 0,
        right: 0,
        width: '100%',
        padding: 0,
        border: 'none',
        background: 'none',
        fontSize: 'inherit',
        fontFamily: 'inherit',
        lineHeight: 'inherit',
        textAlign: 'center',
        bottom: '-10px',
        fontWeight: 700,
        cursor: 'pointer',
        color: 'var(--semi-color-link)',
    } as const;
</script>

<template>
    <Button aria-controls="collapsible-height" :aria-expanded="isOpen" @click="toggle">Toggle</Button>
    <div :style="{ position: 'relative' }">
        <Collapsible id="collapsible-height" :collapseHeight="60" :isOpen="isOpen" :style="maskStyle">
            <ul>
                <li>
                    <p>Semi Design 以内容优先进行设计。</p>
                </li>
                <li>
                    <p>更容易地自定义主题。</p>
                </li>
                <li>
                    <p>适用国际化场景。</p>
                </li>
                <li>
                    <p>效率场景加入人性化关怀。</p>
                </li>
            </ul>
        </Collapsible>
        <button v-if="!isOpen" aria-controls="collapsible-height" :aria-expanded="isOpen" :style="linkStyle" type="button" @click="toggle">+ Show More</button>
    </div>
</template>

API reference

Props

Property	Description	Type	Default
isOpen	Whether the content area is expanded.	`boolean`	`semiDefault("Collapsible", "isOpen", false)`
duration	Animation duration in milliseconds.	`number`	`semiDefault("Collapsible", "duration", 250)`
motion	Whether to enable the animation.	`boolean`	`semiDefault("Collapsible", "motion", true)`
keepDOM	Whether to keep the DOM tree of the hidden content; it is destroyed by default.	`boolean`	`semiDefault("Collapsible", "keepDOM", false)`
lazyRender	Used with keepDOM; when true, the content is not rendered on mount but after the first expansion.	`boolean`	`semiDefault("Collapsible", "lazyRender", false)`
collapseHeight	Height in pixels when collapsed.	`number`	`semiDefault("Collapsible", "collapseHeight", 0)`
collapseHeightAdaptive	Whether the collapsed height follows the content when it is shorter than collapseHeight.	`boolean`	`semiDefault("Collapsible", "collapseHeightAdaptive", false)`
fade	Whether to fade in and out.	`boolean`	`semiDefault("Collapsible", "fade", false)`
id	id of the inner content element, for the trigger's aria-controls; it does not read the global default.	`string`	`undefined`

Events

Event	Description	Callback parameters
motionEnd	Emitted when the expand or collapse animation ends.	`[]`

Slots

Slot	Description	Scope parameters
default	Content to expand or collapse.	`any`

Exposes

Name	Description	Type
None

class, style and native attributes are passed through attrs and land on the outer wrapper. id is a declared prop and lands on the inner content element; it does not read the global default (a global id would repeat on every instance). A @transitionend from the caller runs together with the component's own handler.

Accessibility

ARIA

Collapsible has id props, the value passed in will be set as the id of the inner content element (not the outer wrapper). The trigger button points at it with aria-controls and reports whether it is open with aria-expanded, see the usage example below.

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

    const collapseId = 'myCollapsible';
    const visible = ref(false);
</script>

<template>
    <Button :aria-expanded="visible" :aria-controls="collapseId" @click="visible = !visible">
        {{ visible ? 'hide' : 'show' }}
    </Button>
    <Collapsible :isOpen="visible" :id="collapseId">
        <div>hide content</div>
    </Collapsible>
</template>

Focus

With collapseHeight of 0, the collapsed content is inert: screen readers skip it and Tab cannot reach it.
With collapseHeight above 0, the visible preview and the clipped part are the same element, and the clipped part cannot be hidden on its own, so the whole content stays readable and focusable and screen reader users get the full text. Do not put links, buttons or other focusable elements in the clipped part, or keyboard focus lands where it cannot be seen.

FAQ

Why Collapsible does not expand as expected?
The expanded height of Collapsible is computed by CSS and does not depend on measuring the node, so toggling isOpen under a parent with display: none still gives the correct expanded height. First check that isOpen follows your state; with collapseHeight above 0, part of the content is visible while collapsed by design.