Components
    Show · Collapse

    Collapse

    Display content areas can be expanded or folded.

    Demos

    How to import

    import { Collapse, Tag } from '@fibrous/semi-ui-solid';

    Collapse.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
    import { Collapse } from '@fibrous/semi-ui-solid';

export default function CollapseDemo() {
    return (
        <Collapse>
            <Collapse.Panel header="This is panel header 1" itemKey="1">
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
            <Collapse.Panel header="This is panel header 2" itemKey="2">
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
            <Collapse.Panel header="This is panel header 3" itemKey="3">
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
        </Collapse>
    );
}

    Accordion

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

    Code
    import { Collapse } from '@fibrous/semi-ui-solid';

export default function CollapseDemo() {
    return (
        <Collapse accordion>
            <Collapse.Panel header="This is panel header 1" itemKey="1">
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
            <Collapse.Panel header="This is panel header 2" itemKey="2">
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
            <Collapse.Panel header="This is panel header 3" itemKey="3">
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
        </Collapse>
    );
}

    Disable Panel

    Use disabled to disabled panel.

    Code
    import { Collapse } from '@fibrous/semi-ui-solid';

export default function CollapseDemo() {
    return (
        <Collapse accordion>
            <Collapse.Panel header="This is panel header 1" itemKey="1" disabled>
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
            <Collapse.Panel header="This is panel header 2" itemKey="2">
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
            <Collapse.Panel header="This is panel header 3" itemKey="3">
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
        </Collapse>
    );
}

    Hide The Panel Icon

    Use showArrow to hide the panel icon.

    Code
    import { Collapse } from '@fibrous/semi-ui-solid';

export default function CollapseDemo() {
    return (
        <Collapse accordion>
            <Collapse.Panel header="This is panel header 1" itemKey="1" showArrow={false}>
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
            <Collapse.Panel header="This is panel header 2" itemKey="2">
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
            <Collapse.Panel header="This is panel header 3" itemKey="3">
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
        </Collapse>
    );
}

    Custom Icon

    You can use expandIcon to set the expanding icon and collapseIcon for folded icon, given as elements such as <IconPlus />. Pass null to show no icon.

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

    Code
    import { IconMinus, IconPlus } from '@fibrous/semi-icons-solid';
import { Collapse } from '@fibrous/semi-ui-solid';

export default function CollapseDemo() {
    return (
        <Collapse expandIcon={<IconPlus />} collapseIcon={<IconMinus />}>
            <Collapse.Panel header="This is panel header 1" itemKey="1">
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
            <Collapse.Panel header="This is panel header 2" itemKey="2">
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
            <Collapse.Panel header="This is panel header 3" itemKey="3">
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
        </Collapse>
    );
}

    Custom Extra Content on the Right-upper Corner

    You can use extra 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, whether header is a string or a JSX element.

    1234
    Recommended
    Code
    import { IconCopy } from '@fibrous/semi-icons-solid';
import { Collapse, Tag } from '@fibrous/semi-ui-solid';

export default function CollapseDemo() {
    return (
        <Collapse>
            <Collapse.Panel header="This is panel header 1" itemKey="1" extra="1234">
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
            <Collapse.Panel header="This is panel header 2" itemKey="2" extra={<IconCopy />}>
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
            <Collapse.Panel
                header="This is panel header 3"
                itemKey="3"
                extra={
                    <Tag color="violet" style={{ margin: '0' }}>
                        Recommended
                    </Tag>
                }
            >
                <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
            </Collapse.Panel>
        </Collapse>
    );
}

    API reference

    Collapse

    Props

    PropertyDescriptionTypeDefault
    accordionAccordion mode.boolean-
    activeKeyControlled property, key of the currently expanded panel; null and the empty string mean all panels are collapsed.string | string[] | null-
    childrenCollapse.Panel panels.JSX.Element-
    clickHeaderToExpandClicking anywhere in the header row toggles the panel; when false only the toggle button and the arrow respond.booleantrue
    collapseIconIcon shown while a panel is expanded, given as an element; IconChevronUp when omitted, and null shows no icon.JSX.Element-
    defaultActiveKeyKey of the panel expanded initially.string | string[]""
    expandIconIcon shown while a panel is collapsed, given as an element; IconChevronDown when omitted, and null shows no icon.JSX.Element-
    expandIconPositionPosition of the expand icon: left or right.'left' | 'right'"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.boolean-
    lazyRenderUsed with keepDOM; when true, panel content is not rendered until the panel is first expanded.booleanfalse
    motionWhether to enable the animation; enabled by default. When omitted it reads the global default of Collapse, then that of Collapsible.boolean-
    onChangeCalled 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).Type(activeKey: string[], event: MouseEvent) => void-

    class, style, ref and native attributes and events (such as id and aria-*) land on the root element of Collapse (.semi-collapse). The first argument of onChange is always a string[], even when activeKey or defaultActiveKey is passed as a string.

    Collapse.Panel

    Props

    PropertyDescriptionTypeDefault
    childrenPanel content.JSX.Element-
    disabledWhether the panel is disabled.booleanfalse
    extraAuxiliary content on the right of the panel header, outside the toggle button; may hold controls.JSX.Element-
    headerPanel header content, rendered inside the toggle button; must not contain interactive elements.JSX.Element-
    itemKeyRequired and unique, matched against activeKey and defaultActiveKey.string-
    onMotionEndCalled when the expand or collapse animation ends.Type() => void-
    showArrowWhether to show the arrow icon.booleantrue

    class, style, ref and native attributes and events 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.

    import { Collapse, Input } from '@fibrous/semi-ui-solid';

() => (
    <Collapse>
        <Collapse.Panel
            header="Panel header"
            extra={
                <span onClick={(e) => e.stopPropagation()}>
                    <Input aria-label="Panel note" />
                </span>
            }
            itemKey="1"
        >
            <p>Hi, bytedance dance dance. This is the docsite of Semi UI. </p>
        </Collapse.Panel>
    </Collapse>
);