Disclosure API

Import

Cimpress UI exports two disclosure-related components:

Disclosure: main component to display a disclosure.
DisclosureGroup: container component that groups related disclosures together, providing layout and shared state management.

import { Disclosure, DisclosureGroup } from '@cimpress-ui/react';

Controlled/uncontrolled usage

This component can be used in a controlled or uncontrolled way.

In the controlled way, this component doesn’t maintain its own internal state, and its value is provided by the parent component. Use the controlled way when you need to be able to change the state of this component in other parts of your application.

In the uncontrolled way, this component maintains its own internal state, and can optionally notify the parent component when its internal state changes. Use the uncontrolled way when you don’t need to change the state of this component in other parts of your application.

I am uncontrolled and expanded by default

import { Disclosure, Stack } from '@cimpress-ui/react';
import { useState } from 'react';

export default function Demo() {
  const [isExpanded, setIsExpanded] = useState(false);

  return (
    <Stack gap={32}>
      <Disclosure title="Controlled" isExpanded={isExpanded} onExpandedChange={setIsExpanded}>
        I am controlled by React state
      </Disclosure>

      <Disclosure title="Uncontrolled collapsed">I am uncontrolled and collapsed by default</Disclosure>

      <Disclosure title="Uncontrolled expanded" defaultExpanded>
        I am uncontrolled and expanded by default
      </Disclosure>
    </Stack>
  );
}

Disclosure group

Preview
Code

Controlled

My favorite fruit is apple!

Uncontrolled

My favorite fruit is apple!

import { Disclosure, DisclosureGroup, type Key, Stack, Text } from '@cimpress-ui/react';
import { useState } from 'react';

export default function Demo() {
  const [expandedKeys, setExpandedKeys] = useState<Set<Key>>(() => new Set(['apple']));

  return (
    <Stack gap={32}>
      <Stack gap={16}>
        <Text as="h2" variant="title-4">
          Controlled
        </Text>

        <DisclosureGroup expandedKeys={expandedKeys} onExpandedChange={setExpandedKeys}>
          <Disclosure id="apple" title="Apple">
            My favorite fruit is apple!
          </Disclosure>
          <Disclosure id="banana" title="Banana">
            My favorite fruit is banana!
          </Disclosure>
          <Disclosure id="cherry" title="Cherry">
            My favorite fruit is cherry!
          </Disclosure>
        </DisclosureGroup>
      </Stack>

      <Stack gap={16}>
        <Text as="h2" variant="title-4">
          Uncontrolled
        </Text>

        <DisclosureGroup defaultExpandedKeys={['apple']}>
          <Disclosure id="apple" title="Apple">
            My favorite fruit is apple!
          </Disclosure>
          <Disclosure id="banana" title="Banana">
            My favorite fruit is banana!
          </Disclosure>
          <Disclosure id="cherry" title="Cherry">
            My favorite fruit is cherry!
          </Disclosure>
        </DisclosureGroup>
      </Stack>
    </Stack>
  );
}

Accessibility notes

Disclosures can be expanded/collapsed by pressing Enter or Space when the disclosure header is focused.

Disclosures use the hidden="until-found" attribute in supported browsers, allowing the disclosure to be automatically expanded when a user’s search term matches the collapsed content.

Disclosure requires a title to remain accessible to assistive technologies. Always provide a non-empty value to the title prop.

Group state management

Expanded state of disclosures within DisclosureGroup cannot be set individually. Please use DisclosureGroup’s expandedKeys/defaultExpandedKeys props instead.

// This won't work! :(
<DisclosureGroup>
  <Disclosure id="fruits" title="Fruits">
    Apple, banana, cherry
  </Disclosure>
  <Disclosure id="vegetables" title="Vegetables" defaultExpanded>
    Carrot, broccoli, arugula
  </Disclosure>
</DisclosureGroup>

// But this will :)
<DisclosureGroup defaultExpandedKeys={['vegetables']}>
  <Disclosure id="fruits" title="Fruits">
    Apple, banana, cherry
  </Disclosure>
  <Disclosure id="vegetables" title="Vegetables">
    Carrot, broccoli, arugula
  </Disclosure>
</DisclosureGroup>

API reference

Disclosure

Displays a collapsible section of content.

See disclosure usage guidelines.

ref Section titled “ ref ” Ref<HTMLDivElement>: The ref type for this component.

DisclosureProps

children * Section titled “ children * ” ReactNode: The content to display when the disclosure is expanded.
title * Section titled “ title * ” string: The title that is always visible in the disclosure header.
id Section titled “ id ” Key: A unique ID for the disclosure when used within a DisclosureGroup.
variant Section titled “ variant ” DisclosureVariant: Determines the visual appearance of the disclosure. If the disclosure is part of a group, this prop has no effect - provide variant to DisclosureGroup instead.

Defaults to 'base' .
size Section titled “ size ” DisclosureSize: Determines the size of the disclosure. If the disclosure is part of a group, this prop has no effect - provide size to DisclosureGroup instead.

Defaults to 'medium' .
iconStart Section titled “ iconStart ” ReactNode: An icon displayed before the disclosure title.

Should not be used when size is set to 'small' as icons won't be displayed at this size.
iconEnd Section titled “ iconEnd ” ReactNode: An icon displayed after the disclosure title.

Should not be used when size is set to 'small' as icons won't be displayed at this size.
badge Section titled “ badge ” ReactNode: The badge displayed in the disclosure header.

Should not be used when size is set to 'small' as the badge won't be displayed at this size.
actions Section titled “ actions ” ReactNode: The actions displayed in the disclosure header.
data-cim-style-root Section titled “ data-cim-style-root ” boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className Section titled “ UNSAFE_className ” string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style Section titled “ UNSAFE_style ” CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.
isDisabled Section titled “ isDisabled ” boolean: Whether the disclosure is disabled.
onExpandedChange Section titled “ onExpandedChange ” (isExpanded: boolean) => void: Handler that is called when the disclosure's expanded state changes.
isExpanded Section titled “ isExpanded ” boolean: Whether the disclosure is expanded (controlled).
defaultExpanded Section titled “ defaultExpanded ” boolean: Whether the disclosure is expanded by default (uncontrolled).

StyleProps

margin Section titled “ margin ” Responsive<Spacing | "auto">: The amount of margin applied to all edges of this component.
marginX Section titled “ marginX ” Responsive<Spacing | "auto">: The amount of margin applied to the left and right edges of this component. Takes priority over margin.
marginY Section titled “ marginY ” Responsive<Spacing | "auto">: The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.
marginTop Section titled “ marginTop ” Responsive<Spacing | "auto">: The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.
marginRight Section titled “ marginRight ” Responsive<Spacing | "auto">: The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.
marginBottom Section titled “ marginBottom ” Responsive<Spacing | "auto">: The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.
marginLeft Section titled “ marginLeft ” Responsive<Spacing | "auto">: The amount of margin applied to the left edge of this component. Takes priority over marginX and margin.

DisclosureGroup

Displays a grouping of related disclosures.

See disclosure usage guidelines.

ref Section titled “ ref ” Ref<HTMLDivElement>: The ref type for this component.

DisclosureGroupProps

children * Section titled “ children * ” ReactNode: The disclosures to group together.
variant Section titled “ variant ” DisclosureVariant: Determines the visual appearance of disclosures within this group.

Defaults to 'base' .
size Section titled “ size ” DisclosureSize: Determines the size of disclosures within this group.

Defaults to 'medium' .
onExpandedChange Section titled “ onExpandedChange ” (keys: Set<Key>) => void: Handler that is called when any disclosure in this group is expanded or collapsed.
id Section titled “ id ” string: The element's unique identifier. See MDN.
data-cim-style-root Section titled “ data-cim-style-root ” boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className Section titled “ UNSAFE_className ” string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style Section titled “ UNSAFE_style ” CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.
allowsMultipleExpanded Section titled “ allowsMultipleExpanded ” boolean: Whether multiple items can be expanded at the same time.
isDisabled Section titled “ isDisabled ” boolean: Whether all items are disabled.
expandedKeys Section titled “ expandedKeys ” Iterable<Key, any, any>: The currently expanded keys in the group (controlled).
defaultExpandedKeys Section titled “ defaultExpandedKeys ” Iterable<Key, any, any>: The initial expanded keys in the group (uncontrolled).

StyleProps

margin Section titled “ margin ” Responsive<Spacing | "auto">: The amount of margin applied to all edges of this component.
marginX Section titled “ marginX ” Responsive<Spacing | "auto">: The amount of margin applied to the left and right edges of this component. Takes priority over margin.
marginY Section titled “ marginY ” Responsive<Spacing | "auto">: The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.
marginTop Section titled “ marginTop ” Responsive<Spacing | "auto">: The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.
marginRight Section titled “ marginRight ” Responsive<Spacing | "auto">: The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.
marginBottom Section titled “ marginBottom ” Responsive<Spacing | "auto">: The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.
marginLeft Section titled “ marginLeft ” Responsive<Spacing | "auto">: The amount of margin applied to the left edge of this component. Takes priority over marginX and margin.

Disclosure API

Import

Controlled/uncontrolled usage

Single disclosure

Controlled

Controlled

Uncontrolled collapsed

Uncontrolled collapsed

Uncontrolled expanded

Uncontrolled expanded

Disclosure group

Controlled

Apple

Apple

Banana

Banana

Cherry

Cherry

Uncontrolled

Apple

Apple

Banana

Banana

Cherry

Cherry

Accessibility notes

Group state management

API reference

Disclosure

ref

children *

title *

id

variant

size

iconStart

iconEnd

badge

actions

data-cim-style-root

UNSAFE_className

UNSAFE_style

isDisabled

onExpandedChange

isExpanded

defaultExpanded

margin

marginX

marginY

marginTop

marginRight

marginBottom

marginLeft

DisclosureGroup

ref

children *

variant

size

onExpandedChange

id

data-cim-style-root

UNSAFE_className

UNSAFE_style

allowsMultipleExpanded

isDisabled

expandedKeys

defaultExpandedKeys

margin

marginX

marginY

marginTop

marginRight

marginBottom

marginLeft