Module

View source on GitHub

A Module is a container that holds content about one subject. Its contents can be visible at all times, or expand and collapse as individual modules or a group of modules.

Static Module Props

Name	Type	Default
`id` Required	`string`	-
	Unique id to identify this Module
`badgeText`	`string`	-
	Add a badge displayed after the title. Will not be displayed if `title` is not provided. Be sure to localize the text.
`children`	`React.Node`	-
	Content to display underneath Module title
`icon`	`string`	-
	Name of icon to display in front of title
`iconAccessibilityLabel`	`string`	-
	Label to provide information about the icon used for screen readers. Be sure to localize the label.
`title`	`string`	-
	Title of this Module. Be sure to localize the text.
`type`	`"info" \| "error"`	`"info"`
	If set to `error`, displays error icon and changes title to red text

Expandable Module Props

Name	Type	Default
`accessibilityCollapseLabel` Required	`string`	-
	Label used to communicate to screen readers which module will be collapsed when interacting with the title button. Should be something clear, like "Collapse Security Policies Module". Be sure to localize the label.
`accessibilityExpandLabel` Required	`string`	-
	Label used to communicate to screen readers which module will be expanded when interacting with the title button. Should be something clear, like "Expand Security Policies Module". Be sure to localize the label.
`id` Required	`string`	-
	Unique id to identify this Module
`items` Required	`Array<{\| badgeText?: string, children: ?React.Node, icon?: $Keys<typeof icons>, iconAccessibilityLabel?: string, summary?: Array<string>, title: string, type?: "info" \| "error" \|}>`	-
	Array of modules displayed in a stack. Only one item can be expanded at a time.
`expandedIndex`	`?number`	-
	The 0-based index indicating the item that should currently be expanded. This must be updated via onExpandedChange to ensure the correct item is expanded.
`onExpandedChange`	`(?number) => void`	-
	Callback executed whenever any module item is expanded or collapsed. It receives the index of the currently expanded module, or null if none are expanded.

Usage guidelines

When to Use

Grouping and organizing content to keep the page clean and digestible.
Displaying additional related content about a particular subject.
Enabling users to reveal or hide additional content as necessary (with Expandable variant).

When Not to Use

In a layout that conveys a clear sense of information hierarchy. Use SegmentedControl instead.
When long content can’t be displayed all at once, and scrolling is necessary.
When there is insufficient content to condense, as collapsing can increase cognitive load and interaction cost. Consider the static variant of Module.
When the content is crucial to read in full. Consider the static variant instead.

Static

A Module is a container that can hold any content, and can optionally have a title that describes the content inside. The default, static Module is used to display information that should always be visible.

This is example content.

Title

This is example content.

function ModuleExample() {
  return (
    <Flex direction="column" gap={2} maxWidth={800}>
      <Module id="ModuleExample - default - 1">
        <Text size="md">This is example content.</Text>
      </Module>

      <Module id="ModuleExample - default - 2" title="Title">
        <Text size="md">This is example content.</Text>
      </Module>
    </Flex>
  );
}

function ModuleExample() {
  return (
    <Flex direction="column" gap={2} maxWidth={800}>
      <Module id="ModuleExample - default - 1">
        <Text size="md">This is example content.</Text>
      </Module>
      <Module id="ModuleExample - default - 2" title="Title">
        <Text size="md">This is example content.</Text>
      </Module>
    </Flex>
  );
}

Static - Icon

An Icon can be provided to be placed before the title.

It is recommended that icons be used sparingly to convey additional information, and instead should simply reinforce information in the title. Be sure to provide an iconAccessibilityLabel.

Title

This is example content.

function ModuleExample() {
  return (
    <Box column={12} maxWidth={800} padding={2}>
      <Module
        icon="lock"
        iconAccessibilityLabel="Module Locked - check permission settings"
        id="ModuleExample - icon"
        title="Title"
        >
        <Text size="md">This is example content.</Text>
      </Module>
    </Box>
  );
}

function ModuleExample() {
  return (
    <Box column={12} maxWidth={800} padding={2}>
      <Module
        icon="lock"
        iconAccessibilityLabel="Module Locked - check permission settings"
        id="ModuleExample - icon"
        title="Title"
        >
        <Text size="md">This is example content.</Text>
      </Module>
    </Box>
  );
}

Static - Badge

Badge text can be provided, which will be displayed after the title. Note that if no title text is provided, the badge will not be displayed.

Title

Try it out!

This is example content.

function ModuleExample() {
  return (
    <Box column={12} maxWidth={800} padding={2}>
      <Module
        badgeText="Try it out!"
        id="ModuleExample - badge"
        title="Title"
        >
        <Text size="md">This is example content.</Text>
      </Module>
    </Box>
  );
}

function ModuleExample() {
  return (
    <Box column={12} maxWidth={800} padding={2}>
      <Module
        badgeText="Try it out!"
        id="ModuleExample - badge"
        title="Title"
        >
        <Text size="md">This is example content.</Text>
      </Module>
    </Box>
  );
}

Static - Error

Personal Info

This is example content.

Enter Your Name

This field can't be blank!

function ModuleExample() {
  const [value, setValue] = React.useState('');

  return (
    <Box column={12} maxWidth={800} padding={2}>
      <Module
        id="ModuleExample - error"
        title="Personal Info"
        type={!value ? "error" : "info"}
      >
        <Flex direction="column" gap={4}>
          <Text size="md">This is example content.</Text>

          <TextField
            errorMessage={!value ? "This field can't be blank!" : null}
            id="first-name"
            label="Enter Your Name"
            onChange={({ value }) => setValue(value)}
            value={value}
          />
        </Flex>
      </Module>
    </Box>
  );
}

function ModuleExample() {
  const [value, setValue] = React.useState('');
  return (
    <Box column={12} maxWidth={800} padding={2}>
      <Module
        id="ModuleExample - error"
        title="Personal Info"
        type={!value ? "error" : "info"}
      >
        <Flex direction="column" gap={4}>
          <Text size="md">This is example content.</Text>
          <TextField
            errorMessage={!value ? "This field can't be blank!" : null}
            id="first-name"
            label="Enter Your Name"
            onChange={({ value }) => setValue(value)}
            value={value}
          />
        </Flex>
      </Module>
    </Box>
  );
}

Expandable

Modules can also allow for expanding and collapsing content. The title is required and always present. The collapsed state shows optional summary content, while the expanded state shows any content desired.

Title

summary1

summary2

summary3

function ModuleExample1() {
  return (
    <Box column={12} maxWidth={800} padding={2}>
      <Module.Expandable
        accessibilityExpandLabel="Expand the module"
        accessibilityCollapseLabel="Collapse the module"
        id="ModuleExample - default"
        items={[
          {
            children: <Text size="md">Children1</Text>,
            summary: ['summary1', 'summary2', 'summary3'],
            title: 'Title',
          }]}>
      </Module.Expandable>
    </Box>
  );
}

function ModuleExample1() {
  return (
    <Box column={12} maxWidth={800} padding={2}>
      <Module.Expandable
        accessibilityExpandLabel="Expand the module"
        accessibilityCollapseLabel="Collapse the module"
        id="ModuleExample - default"
        items={[
          {
            children: <Text size="md">Children1</Text>,
            summary: ['summary1', 'summary2', 'summary3'],
            title: 'Title',
          }]}>
      </Module.Expandable>
    </Box>
  );
}

Expandable - Group

Multiple expandable items can be stacked together into a Module group. However, only one Module will be expanded at any time.

Title1

summary1

Title2

summary2

Title3

summary3

function ModuleExample2() {
  return (
    <Box column={12} maxWidth={800} padding={2}>
      <Module.Expandable
        id="ModuleExample2"
        accessibilityExpandLabel="Expand the module"
        accessibilityCollapseLabel="Collapse the module"
        items={[
          {
            children: <Text size="md">Children1</Text>,
            summary: ['summary1'],
            title: 'Title1',
          },
          {
            children: <Text size="md">Children2</Text>,
            summary: ['summary2'],
            title: 'Title2',
          },
          {
            children: <Text size="md">Children3</Text>,
            summary: ['summary3'],
            title: 'Title3',
          }]}>
      </Module.Expandable>
    </Box>
  );
}

function ModuleExample2() {
  return (
    <Box column={12} maxWidth={800} padding={2}>
      <Module.Expandable
        id="ModuleExample2"
        accessibilityExpandLabel="Expand the module"
        accessibilityCollapseLabel="Collapse the module"
        items={[
          {
            children: <Text size="md">Children1</Text>,
            summary: ['summary1'],
            title: 'Title1',
          },
          {
            children: <Text size="md">Children2</Text>,
            summary: ['summary2'],
            title: 'Title2',
          },
          {
            children: <Text size="md">Children3</Text>,
            summary: ['summary3'],
            title: 'Title3',
          }]}>
      </Module.Expandable>
    </Box>
  );
}

Expandable - Icon and Badge

An Icon can be provided to be placed before the title.
It is recommended that icons be used sparingly to convey additional information, and instead should simply reinforce information in the title. Be sure to provide an iconAccessibilityLabel.

Badge text can also be provided, which will be displayed after the title.

Example with icon

Example with badge

Try it out!

function ModuleExample3() {
  return (
    <Box column={12} maxWidth={800} padding={2}>
      <Module.Expandable
        accessibilityExpandLabel="Expand the module"
        accessibilityCollapseLabel="Collapse the module"
        id="ModuleExample3"
        items={[
          {
            children: <Text size="md">Children1</Text>,
            icon: 'lock',
            iconAccessibilityLabel: "title icon",
            title: 'Example with icon',
          },
          {
            badgeText: 'Try it out!',
            children: <Text size="md">Children2</Text>,
            title: 'Example with badge',
          },
        ]}>
      </Module.Expandable>
    </Box>
  );
}

function ModuleExample3() {
  return (
    <Box column={12} maxWidth={800} padding={2}>
      <Module.Expandable
        accessibilityExpandLabel="Expand the module"
        accessibilityCollapseLabel="Collapse the module"
        id="ModuleExample3"
        items={[
          {
            children: <Text size="md">Children1</Text>,
            icon: 'lock',
            iconAccessibilityLabel: "title icon",
            title: 'Example with icon',
          },
          {
            badgeText: 'Try it out!',
            children: <Text size="md">Children2</Text>,
            title: 'Example with badge',
          },
        ]}>
      </Module.Expandable>
    </Box>
  );
}

Expandable - Error

Personal Info

Name is missing

function ModuleExample4() {
  const [value, setValue] = React.useState('');
  const moduleType = !value ? 'error' : 'info';
  const summaryInfo = !value ? 'Name is missing' : 'Name: ' + value;

  return (
    <Box column={12} maxWidth={800} padding={2}>
      <Module.Expandable
        accessibilityExpandLabel="Expand the module"
        accessibilityCollapseLabel="Collapse the module"
        id="ModuleExample4"
        items={[
          {
            children: <Text size="md">
              <TextField
                errorMessage={!value ? "This field can't be blank!" : null}
                id="aboutme"
                label="Enter Your Name"
                onChange={({ value }) => setValue(value)}
                value={value}
              />
            </Text>,
            iconAccessibilityLabel: "error icon",
            summary: [summaryInfo],
            title: 'Personal Info',
            type: moduleType
          }]}>
      </Module.Expandable>
    </Box>
  );
}

function ModuleExample4() {
  const [value, setValue] = React.useState('');
  const moduleType = !value ? 'error' : 'info';
  const summaryInfo = !value ? 'Name is missing' : 'Name: ' + value;
  return (
    <Box column={12} maxWidth={800} padding={2}>
      <Module.Expandable
        accessibilityExpandLabel="Expand the module"
        accessibilityCollapseLabel="Collapse the module"
        id="ModuleExample4"
        items={[
          {
            children: <Text size="md">
              <TextField
                errorMessage={!value ? "This field can't be blank!" : null}
                id="aboutme"
                label="Enter Your Name"
                onChange={({ value }) => setValue(value)}
                value={value}
              />
            </Text>,
            iconAccessibilityLabel: "error icon",
            summary: [summaryInfo],
            title: 'Personal Info',
            type: moduleType
          }]}>
      </Module.Expandable>
    </Box>
  );
}

Example with external control

Step 1

Title1

summary1

Title2

summary2

Step 2

Title1

summary1

Title2

summary2

function ModuleExample5() {
  const [extExpandedId, setExtExpandedId] = React.useState(null);
  const mapIds = {
      'first-0': 0,
      'first-1': 1,
      'second-0': 0,
      'second-1': 1,
  }
  return (
    <Box column={12} maxWidth={800} padding={2}>
      <Flex direction="column" gap={4}>
        <Flex direction="column" gap={2}>
          <Box marginStart={2}>
            <Text>Step 1</Text>
          </Box>

          <Module.Expandable
            accessibilityExpandLabel="Expand the module"
            accessibilityCollapseLabel="Collapse the module"
            expandedIndex={extExpandedId && extExpandedId.startsWith('first') && mapIds[extExpandedId]}
            id="ModuleExampleStep1"
            items={[
              {
                title: 'Title1',
                summary: ['summary1'],
                children: <Text size="md">Children1</Text>,
              },
              {
                title: 'Title2',
                summary: ['summary2'],
                children: <Text size="md">Children2</Text>,
              },
            ]}
            onExpandedChange={(index) => setExtExpandedId(Number.isFinite(index) ? `first-${index}`: index)}
          />
        </Flex>

        <Flex direction="column" gap={2}>
          <Box marginStart={2}>
            <Text>Step 2</Text>
          </Box>

          <Module.Expandable
            id="ModuleExampleStep2"
            accessibilityExpandLabel="Expand the module"
            accessibilityCollapseLabel="Collapse the module"
            expandedIndex={extExpandedId && extExpandedId.startsWith('second') && mapIds[extExpandedId]}
            onExpandedChange={(index) => setExtExpandedId(Number.isFinite(index) ? `second-${index}`: index)}
            items={[
              {
                title: 'Title1',
                summary: ['summary1'],
                children: <Text size="md">Children1</Text>,
              },
              {
                title: 'Title2',
                summary: ['summary2'],
                children: <Text size="md">Children2</Text>,
              },
            ]}
          />
        </Flex>
      </Flex>
    </Box>
  );
}

function ModuleExample5() {
  const [extExpandedId, setExtExpandedId] = React.useState(null);
  const mapIds = {
      'first-0': 0,
      'first-1': 1,
      'second-0': 0,
      'second-1': 1,
  }
  return (
    <Box column={12} maxWidth={800} padding={2}>
      <Flex direction="column" gap={4}>
        <Flex direction="column" gap={2}>
          <Box marginStart={2}>
            <Text>Step 1</Text>
          </Box>
          <Module.Expandable
            accessibilityExpandLabel="Expand the module"
            accessibilityCollapseLabel="Collapse the module"
            expandedIndex={extExpandedId && extExpandedId.startsWith('first') && mapIds[extExpandedId]}
            id="ModuleExampleStep1"
            items={[
              {
                title: 'Title1',
                summary: ['summary1'],
                children: <Text size="md">Children1</Text>,
              },
              {
                title: 'Title2',
                summary: ['summary2'],
                children: <Text size="md">Children2</Text>,
              },
            ]}
            onExpandedChange={(index) => setExtExpandedId(Number.isFinite(index) ? `first-${index}`: index)}
          />
        </Flex>
        <Flex direction="column" gap={2}>
          <Box marginStart={2}>
            <Text>Step 2</Text>
          </Box>
          <Module.Expandable
            id="ModuleExampleStep2"
            accessibilityExpandLabel="Expand the module"
            accessibilityCollapseLabel="Collapse the module"
            expandedIndex={extExpandedId && extExpandedId.startsWith('second') && mapIds[extExpandedId]}
            onExpandedChange={(index) => setExtExpandedId(Number.isFinite(index) ? `second-${index}`: index)}
            items={[
              {
                title: 'Title1',
                summary: ['summary1'],
                children: <Text size="md">Children1</Text>,
              },
              {
                title: 'Title2',
                summary: ['summary2'],
                children: <Text size="md">Children2</Text>,
              },
            ]}
          />
        </Flex>
      </Flex>
    </Box>
  );
}

Edit page on GitHub