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 Ref<HTMLDivElement>: The ref type for this component.

DisclosureProps

children * ReactNode: The content to display when the disclosure is expanded.
title * string: The title that is always visible in the disclosure header.
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 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 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 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 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 ReactNode: The actions displayed in the disclosure header.
data-cim-style-root boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
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 CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.
isDisabled boolean: Whether the disclosure is disabled.
onExpandedChange (isExpanded: boolean) => void: Handler that is called when the disclosure's expanded state changes.
isExpanded boolean: Whether the disclosure is expanded (controlled).
defaultExpanded boolean: Whether the disclosure is expanded by default (uncontrolled).
id Key: An id for the disclosure when used within a DisclosureGroup, matching the id used in expandedKeys.

StyleProps

margin Responsive<Spacing | "auto">: The amount of margin applied to all edges of this component.
marginX Responsive<Spacing | "auto">: The amount of margin applied to the left and right edges of this component. Takes priority over margin.
marginY Responsive<Spacing | "auto">: The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.
marginTop Responsive<Spacing | "auto">: The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.
marginRight Responsive<Spacing | "auto">: The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.
marginBottom Responsive<Spacing | "auto">: The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.
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 Ref<HTMLDivElement>: The ref type for this component.

DisclosureGroupProps

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

Defaults to 'base' .
size DisclosureSize: Determines the size of disclosures within this group.

Defaults to 'medium' .
id string: The element's unique identifier. See MDN.
data-cim-style-root boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
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 CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.
allowsMultipleExpanded boolean: Whether multiple items can be expanded at the same time.
isDisabled boolean: Whether all items are disabled.
expandedKeys Iterable<Key, any, any>: The currently expanded keys in the group (controlled).
defaultExpandedKeys Iterable<Key, any, any>: The initial expanded keys in the group (uncontrolled).
onExpandedChange (keys: Set<Key>) => any: Handler that is called when items are expanded or collapsed.

StyleProps

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