ContextualHelp

Contextual help shows a user extra information about the state of an adjacent component, or a total view.

Example#

<ContextualHelp variant="info">
  <Heading>Need help?</Heading>
  <Content>
    <Text>
      If you're having issues accessing your account, contact our customer
      support team for help.
    </Text>
  </Content>
</ContextualHelp>

<ContextualHelp variant="info">
  <Heading>Need help?</Heading>
  <Content>
    <Text>
      If you're having issues accessing your account,
      contact our customer support team for help.
    </Text>
  </Content>
</ContextualHelp>

<ContextualHelp variant="info">
  <Heading>
    Need help?
  </Heading>
  <Content>
    <Text>
      If you're having
      issues accessing
      your account,
      contact our
      customer support
      team for help.
    </Text>
  </Content>
</ContextualHelp>

Content#

Unlike Dialog, the layout in ContextualHelp is very deliberate. Every ContextualHelp component is triggered as a popover where the trigger element is a quiet action button with either a help or info icon. Much like Dialog, however, ContextualHelp has sections that can be populated by providing the following components to your ContextualHelp as children: Heading (title), Content (body), and Footer (link). Each of these components are required in a Spectrum compliant ContextualHelp except for Footer since including a link is optional.

<ContextualHelp variant="help">
  <Heading>What is a segment?</Heading>
  <Content>
    <Text>
      Segments identify who your visitors are, what devices and services they
      use, where they navigated from, and much more.
    </Text>
  </Content>
  <Footer>
    <Link>Learn more about segments</Link>
  </Footer>
</ContextualHelp>

<ContextualHelp variant="help">
  <Heading>What is a segment?</Heading>
  <Content>
    <Text>
      Segments identify who your visitors are, what
      devices and services they use, where they navigated
      from, and much more.
    </Text>
  </Content>
  <Footer>
    <Link>Learn more about segments</Link>
  </Footer>
</ContextualHelp>

<ContextualHelp variant="help">
  <Heading>
    What is a segment?
  </Heading>
  <Content>
    <Text>
      Segments identify
      who your visitors
      are, what devices
      and services they
      use, where they
      navigated from,
      and much more.
    </Text>
  </Content>
  <Footer>
    <Link>
      Learn more about
      segments
    </Link>
  </Footer>
</ContextualHelp>

Placement#

ContextualHelp supports Dialog placement options for when the positioning of the popover needs to customized.

<ContextualHelp variant="info" placement="top start">
  <Heading>Placement</Heading>
  <Content>
    <Text>
      The placement of this contextual help popover has been customized to use
      top start.
    </Text>
  </Content>
</ContextualHelp>

<ContextualHelp variant="info" placement="top start">
  <Heading>Placement</Heading>
  <Content>
    <Text>
      The placement of this contextual help popover has
      been customized to use top start.
    </Text>
  </Content>
</ContextualHelp>

<ContextualHelp
  variant="info"
  placement="top start"
>
  <Heading>
    Placement
  </Heading>
  <Content>
    <Text>
      The placement of
      this contextual
      help popover has
      been customized
      to use top start.
    </Text>
  </Content>
</ContextualHelp>

Events#

ContextualHelp accepts an onOpenChange prop, triggered when the ContextualHelp's popover opens or closes.

The example below uses onOpenChange to update a separate element with the current open state of the Dialog.

function Example() {
  let [state, setState] = React.useState(false);

  return (
    <Flex alignItems="center" gap="size-100">
      <ContextualHelp
        variant="info"
        onOpenChange={(isOpen) => setState(isOpen)}
      >
        <Heading>Permission required</Heading>
        <Content>
          <Text>
            Your admin must grant you permission before you can create a
            segment.
          </Text>
        </Content>
      </ContextualHelp>
      <Text>Current open state: {state.toString()}</Text>
    </Flex>
  );
}

function Example() {
  let [state, setState] = React.useState(false);

  return (
    <Flex alignItems="center" gap="size-100">
      <ContextualHelp
        variant="info"
        onOpenChange={(isOpen) => setState(isOpen)}
      >
        <Heading>Permission required</Heading>
        <Content>
          <Text>
            Your admin must grant you permission before you
            can create a segment.
          </Text>
        </Content>
      </ContextualHelp>
      <Text>Current open state: {state.toString()}</Text>
    </Flex>
  );
}

function Example() {
  let [state, setState] =
    React.useState(
      false
    );

  return (
    <Flex
      alignItems="center"
      gap="size-100"
    >
      <ContextualHelp
        variant="info"
        onOpenChange={(
          isOpen
        ) =>
          setState(
            isOpen
          )}
      >
        <Heading>
          Permission
          required
        </Heading>
        <Content>
          <Text>
            Your admin
            must grant
            you
            permission
            before you
            can create a
            segment.
          </Text>
        </Content>
      </ContextualHelp>
      <Text>
        Current open
        state:{' '}
        {state
          .toString()}
      </Text>
    </Flex>
  );
}

Props#

Visual options#

Info#

Use the info icon for brief, specific, contextual guidance. This is best for supplemental or nice-to-know information, in-line with a label or a component (if there is no label). The content for an info icon’s popover should be instructive in tone.

<ContextualHelp variant="info">
  <Heading>Permission required</Heading>
  <Content>
    <Text>
      Your admin must grant you permission before you can create a segment.
    </Text>
  </Content>
</ContextualHelp>

<ContextualHelp variant="info">
  <Heading>Permission required</Heading>
  <Content>
    <Text>
      Your admin must grant you permission before you can
      create a segment.
    </Text>
  </Content>
</ContextualHelp>

<ContextualHelp variant="info">
  <Heading>
    Permission required
  </Heading>
  <Content>
    <Text>
      Your admin must
      grant you
      permission before
      you can create a
      segment.
    </Text>
  </Content>
</ContextualHelp>

Help#

Use the help icon for content that offers more detailed, in-depth guidance about a task, UI element, tool, or keyboard shortcuts. This may include an image, video, or link and should be helpful in tone.

<ContextualHelp variant="help">
  <Heading>What is a segment?</Heading>
  <Content>
    <Text>
      Segments identify who your visitors are, what devices and services they
      use, where they navigated from, and much more.
    </Text>
  </Content>
  <Footer>
    <Link>Learn more about segments</Link>
  </Footer>
</ContextualHelp>

<ContextualHelp variant="help">
  <Heading>What is a segment?</Heading>
  <Content>
    <Text>
      Segments identify who your visitors are, what
      devices and services they use, where they navigated
      from, and much more.
    </Text>
  </Content>
  <Footer>
    <Link>Learn more about segments</Link>
  </Footer>
</ContextualHelp>

<ContextualHelp variant="help">
  <Heading>
    What is a segment?
  </Heading>
  <Content>
    <Text>
      Segments identify
      who your visitors
      are, what devices
      and services they
      use, where they
      navigated from,
      and much more.
    </Text>
  </Content>
  <Footer>
    <Link>
      Learn more about
      segments
    </Link>
  </Footer>
</ContextualHelp>

Testing#

The ContextualHelpTrigger features an overlay that transitions in and out of the page as it is opened and closed. Please see the following sections in the testing docs for more information on how to handle these behaviors in your test suite.

Timers

Please also refer to React Spectrum's test suite if you find that the above isn't sufficient when resolving issues in your own test cases.