ContextualHelp

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

install	`yarn add @react-spectrum/contextualhelp`
version	3.0.4
usage	`import {ContextualHelp} from '@react-spectrum/contextualhelp'`

View guidelines

Spectrum

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#

Name	Type	Default	Description
`children`	`ReactNode`	—	Contents of the Contextual Help popover.
`variant`	`'help' \| 'info'`	`'help'`	Indicates whether contents are informative or provides helpful guidance.
`placement`	`Placement`	`'bottom start'`	The placement of the popover with respect to the action button.
`isOpen`	`boolean`	—	Whether the overlay is open by default (controlled).
`defaultOpen`	`boolean`	—	Whether the overlay is open by default (uncontrolled).
`containerPadding`	`number`	`12`	The placement padding that should be applied between the element and its surrounding container.
`offset`	`number`	`0`	The additional offset applied along the main axis between the element and its anchor element.
`crossOffset`	`number`	`0`	The additional offset applied along the cross axis between the element and its anchor element.
`shouldFlip`	`boolean`	`true`	Whether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely.

Events

Name	Type	Default	Description
`onOpenChange`	`( (isOpen: boolean )) => void`	—	Handler that is called when the overlay's open state changes.

Layout

Name	Type	Default	Description
`flex`	`Responsive<string \| number \| boolean>`	—	When used in a flex layout, specifies how the element will grow or shrink to fit the space available. See MDN.
`flexGrow`	`Responsive<number>`	—	When used in a flex layout, specifies how the element will grow to fit the space available. See MDN.
`flexShrink`	`Responsive<number>`	—	When used in a flex layout, specifies how the element will shrink to fit the space available. See MDN.
`flexBasis`	`Responsive<number \| string>`	—	When used in a flex layout, specifies the initial main size of the element. See MDN.
`alignSelf`	`Responsive<'auto' \| 'normal' \| 'start' \| 'end' \| 'center' \| 'flex-start' \| 'flex-end' \| 'self-start' \| 'self-end' \| 'stretch'>`	—	Overrides the `alignItems` property of a flex or grid container. See MDN.
`justifySelf`	`Responsive<'auto' \| 'normal' \| 'start' \| 'end' \| 'flex-start' \| 'flex-end' \| 'self-start' \| 'self-end' \| 'center' \| 'left' \| 'right' \| 'stretch'>`	—	Specifies how the element is justified inside a flex or grid container. See MDN.
`order`	`Responsive<number>`	—	The layout order for the element within a flex or grid container. See MDN.
`gridArea`	`Responsive<string>`	—	When used in a grid layout, specifies the named grid area that the element should be placed in within the grid. See MDN.
`gridColumn`	`Responsive<string>`	—	When used in a grid layout, specifies the column the element should be placed in within the grid. See MDN.
`gridRow`	`Responsive<string>`	—	When used in a grid layout, specifies the row the element should be placed in within the grid. See MDN.
`gridColumnStart`	`Responsive<string>`	—	When used in a grid layout, specifies the starting column to span within the grid. See MDN.
`gridColumnEnd`	`Responsive<string>`	—	When used in a grid layout, specifies the ending column to span within the grid. See MDN.
`gridRowStart`	`Responsive<string>`	—	When used in a grid layout, specifies the starting row to span within the grid. See MDN.
`gridRowEnd`	`Responsive<string>`	—	When used in a grid layout, specifies the ending row to span within the grid. See MDN.

Spacing

Name	Type	Default	Description
`margin`	`Responsive<DimensionValue>`	—	The margin for all four sides of the element. See MDN.
`marginTop`	`Responsive<DimensionValue>`	—	The margin for the top side of the element. See MDN.
`marginBottom`	`Responsive<DimensionValue>`	—	The margin for the bottom side of the element. See MDN.
`marginStart`	`Responsive<DimensionValue>`	—	The margin for the logical start side of the element, depending on layout direction. See MDN.
`marginEnd`	`Responsive<DimensionValue>`	—	The margin for the logical end side of an element, depending on layout direction. See MDN.
`marginX`	`Responsive<DimensionValue>`	—	The margin for both the left and right sides of the element. See MDN.
`marginY`	`Responsive<DimensionValue>`	—	The margin for both the top and bottom sides of the element. See MDN.

Sizing

Name	Type	Default	Description
`width`	`Responsive<DimensionValue>`	—	The width of the element. See MDN.
`minWidth`	`Responsive<DimensionValue>`	—	The minimum width of the element. See MDN.
`maxWidth`	`Responsive<DimensionValue>`	—	The maximum width of the element. See MDN.
`height`	`Responsive<DimensionValue>`	—	The height of the element. See MDN.
`minHeight`	`Responsive<DimensionValue>`	—	The minimum height of the element. See MDN.
`maxHeight`	`Responsive<DimensionValue>`	—	The maximum height of the element. See MDN.

Positioning

Name	Type	Default	Description
`position`	`Responsive<'static' \| 'relative' \| 'absolute' \| 'fixed' \| 'sticky'>`	—	Specifies how the element is positioned. See MDN.
`top`	`Responsive<DimensionValue>`	—	The top position for the element. See MDN.
`bottom`	`Responsive<DimensionValue>`	—	The bottom position for the element. See MDN.
`left`	`Responsive<DimensionValue>`	—	The left position for the element. See MDN. Consider using `start` instead for RTL support.
`right`	`Responsive<DimensionValue>`	—	The right position for the element. See MDN. Consider using `start` instead for RTL support.
`start`	`Responsive<DimensionValue>`	—	The logical start position for the element, depending on layout direction. See MDN.
`end`	`Responsive<DimensionValue>`	—	The logical end position for the element, depending on layout direction. See MDN.
`zIndex`	`Responsive<number>`	—	The stacking order for the element. See MDN.
`isHidden`	`Responsive<boolean>`	—	Hides the element.

Accessibility

Name	Type	Default	Description
`id`	`string`	—	The element's unique identifier. See MDN.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.

Advanced

Name	Type	Default	Description
`UNSAFE_className`	`string`	—	Sets the CSS className for the element. Only use as a last resort. Use style props instead.
`UNSAFE_style`	`CSSProperties`	—	Sets inline style for the element. Only use as a last resort. Use style props instead.

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>