ContextualHelp

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

installyarn add @react-spectrum/contextualhelp
version3.0.1
usageimport {ContextualHelp} from '@react-spectrum/contextualhelp'
View repository
GitHub
View package
NPM

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#

NameTypeDefaultDescription
childrenReactNode—Contents of the Contextual Help popover.
variant'help' | 'info''help'Indicates whether contents are informative or provides helpful guidance.
placementPlacement'bottom start'The placement of the popover with respect to the action button.
isOpenboolean—Whether the overlay is open by default (controlled).
defaultOpenboolean—Whether the overlay is open by default (uncontrolled).
containerPaddingnumber12The placement padding that should be applied between the element and its surrounding container.
offsetnumber0The additional offset applied along the main axis between the element and its anchor element.
crossOffsetnumber0The additional offset applied along the cross axis between the element and its anchor element.
shouldFlipbooleantrueWhether 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
NameTypeDefaultDescription
onOpenChange( (isOpen: boolean )) => void—Handler that is called when the overlay's open state changes.
Layout
NameTypeDefaultDescription
flexResponsive<string | number | boolean>—When used in a flex layout, specifies how the element will grow or shrink to fit the space available. See MDN.
flexGrowResponsive<number>—When used in a flex layout, specifies how the element will grow to fit the space available. See MDN.
flexShrinkResponsive<number>—When used in a flex layout, specifies how the element will shrink to fit the space available. See MDN.
flexBasisResponsive<number | string>—When used in a flex layout, specifies the initial main size of the element. See MDN.
alignSelfResponsive<'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.
justifySelfResponsive<'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.
orderResponsive<number>—The layout order for the element within a flex or grid container. See MDN.
gridAreaResponsive<string>—When used in a grid layout, specifies the named grid area that the element should be placed in within the grid. See MDN.
gridColumnResponsive<string>—When used in a grid layout, specifies the column the element should be placed in within the grid. See MDN.
gridRowResponsive<string>—When used in a grid layout, specifies the row the element should be placed in within the grid. See MDN.
gridColumnStartResponsive<string>—When used in a grid layout, specifies the starting column to span within the grid. See MDN.
gridColumnEndResponsive<string>—When used in a grid layout, specifies the ending column to span within the grid. See MDN.
gridRowStartResponsive<string>—When used in a grid layout, specifies the starting row to span within the grid. See MDN.
gridRowEndResponsive<string>—When used in a grid layout, specifies the ending row to span within the grid. See MDN.
Spacing
NameTypeDefaultDescription
marginResponsive<DimensionValue>—The margin for all four sides of the element. See MDN.
marginTopResponsive<DimensionValue>—The margin for the top side of the element. See MDN.
marginBottomResponsive<DimensionValue>—The margin for the bottom side of the element. See MDN.
marginStartResponsive<DimensionValue>—The margin for the logical start side of the element, depending on layout direction. See MDN.
marginEndResponsive<DimensionValue>—The margin for the logical end side of an element, depending on layout direction. See MDN.
marginXResponsive<DimensionValue>—The margin for both the left and right sides of the element. See MDN.
marginYResponsive<DimensionValue>—The margin for both the top and bottom sides of the element. See MDN.
Sizing
NameTypeDefaultDescription
widthResponsive<DimensionValue>—The width of the element. See MDN.
minWidthResponsive<DimensionValue>—The minimum width of the element. See MDN.
maxWidthResponsive<DimensionValue>—The maximum width of the element. See MDN.
heightResponsive<DimensionValue>—The height of the element. See MDN.
minHeightResponsive<DimensionValue>—The minimum height of the element. See MDN.
maxHeightResponsive<DimensionValue>—The maximum height of the element. See MDN.
Positioning
NameTypeDefaultDescription
positionResponsive<'static' | 'relative' | 'absolute' | 'fixed' | 'sticky'>—Specifies how the element is positioned. See MDN.
topResponsive<DimensionValue>—The top position for the element. See MDN.
bottomResponsive<DimensionValue>—The bottom position for the element. See MDN.
leftResponsive<DimensionValue>—The left position for the element. See MDN. Consider using start instead for RTL support.
rightResponsive<DimensionValue>—The right position for the element. See MDN. Consider using start instead for RTL support.
startResponsive<DimensionValue>—The logical start position for the element, depending on layout direction. See MDN.
endResponsive<DimensionValue>—The logical end position for the element, depending on layout direction. See MDN.
zIndexResponsive<number>—The stacking order for the element. See MDN.
isHiddenResponsive<boolean>—Hides the element.
Accessibility
NameTypeDefaultDescription
idstring—The element's unique identifier. See MDN.
aria-labelstring—Defines a string value that labels the current element.
aria-labelledbystring—Identifies the element (or elements) that labels the current element.
aria-describedbystring—Identifies the element (or elements) that describes the object.
aria-detailsstring—Identifies the element (or elements) that provide a detailed, extended description for the object.
Advanced
NameTypeDefaultDescription
UNSAFE_classNamestring—Sets the CSS className for the element. Only use as a last resort. Use style props instead.
UNSAFE_styleCSSProperties—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>