Background

When you render a portalled component (like a Popover or OptionMenu) inside another portalled component, the inner component renders in a separate DOM node via a React portal. This can cause the outer component to lose focus and close unexpectedly, since the inner component's DOM is outside the outer component's focus trap.

The nested portal pattern solves this by:

1. Marking the inner component with className="nested-portal" so the outer component knows not to close when focus moves into it
2. Manually controlling the outer component's focus trap when needed

Using className="nested-portal"

For simple cases — like a Popover or OptionMenu rendered inside another Popover — adding className="nested-portal" to the inner component is all you need.

Editable example
<Popover
  button={(buttonProps) => (
    <Button type="secondary" {...buttonProps}>
      Open settings
    </Button>
  )}
>
  <Stack gap="s" padding="s">
    <Text>Background settings</Text>
    <Popover
      className="nested-portal"
      size="small"
      button={(buttonProps) => (
        <MenuItem {...buttonProps}>Pick a color</MenuItem>
      )}
    >
      <Stack gap="s" padding="s">
        <Text>Color picker content</Text>
        <Button>Apply</Button>
      </Stack>
    </Popover>
  </Stack>
</Popover>
<Popover
  button={(buttonProps) => (
    <Button type="secondary" {...buttonProps}>
      Open settings
    </Button>
  )}
>
  <Stack gap="s" padding="s">
    <Text>Background settings</Text>
    <Popover
      className="nested-portal"
      size="small"
      button={(buttonProps) => (
        <MenuItem {...buttonProps}>Pick a color</MenuItem>
      )}
    >
      <Stack gap="s" padding="s">
        <Text>Color picker content</Text>
        <Button>Apply</Button>
      </Stack>
    </Popover>
  </Stack>
</Popover>

Nested portals inside OptionMenu

When rendering a portalled component inside an OptionMenu, you need to also manage the OptionMenu's focus trap. Use OptionMenuNestedPortalConsumer to get access to focus trap controls, and toggle them when the nested component opens and closes.

Editable example
<OptionMenu
  button={<Button decorator={ButtonDecorator.Dropdown}>Options</Button>}
>
  <OptionMenuItem>Option 1</OptionMenuItem>
  <OptionMenuItem>Option 2</OptionMenuItem>
  <OptionMenuNestedPortalConsumer>
    {(context) => (
      <Popover
        className="nested-portal"
        position="right"
        button={(buttonProps) => (
          <OptionMenuItem {...buttonProps} closeOnClick={false}>
            Nested Portal
          </OptionMenuItem>
        )}
        onChange={(isOpen) => {
          if (isOpen) {
            context.deactivateFocusTrap();
          } else {
            context.activateFocusTrap();
          }
        }}
      >
        <Stack gap="s">
          <Text>You can move focus into this nested portal</Text>
          <Button>Button</Button>
        </Stack>
      </Popover>
    )}
  </OptionMenuNestedPortalConsumer>
</OptionMenu>
<OptionMenu
  button={<Button decorator={ButtonDecorator.Dropdown}>Options</Button>}
>
  <OptionMenuItem>Option 1</OptionMenuItem>
  <OptionMenuItem>Option 2</OptionMenuItem>
  <OptionMenuNestedPortalConsumer>
    {(context) => (
      <Popover
        className="nested-portal"
        position="right"
        button={(buttonProps) => (
          <OptionMenuItem {...buttonProps} closeOnClick={false}>
            Nested Portal
          </OptionMenuItem>
        )}
        onChange={(isOpen) => {
          if (isOpen) {
            context.deactivateFocusTrap();
          } else {
            context.activateFocusTrap();
          }
        }}
      >
        <Stack gap="s">
          <Text>You can move focus into this nested portal</Text>
          <Button>Button</Button>
        </Stack>
      </Popover>
    )}
  </OptionMenuNestedPortalConsumer>
</OptionMenu>

Key points for OptionMenu nesting:

• Wrap the nested component in OptionMenuNestedPortalConsumer to access the focus trap context
• Call context.deactivateFocusTrap() when the nested component opens
• Call context.activateFocusTrap() when the nested component closes
• Set closeOnClick={false} on the trigger OptionMenuItem to prevent the menu from closing when the nested component is activated

Nested OptionMenu inside another portalled component

You can also nest an OptionMenu inside a Popover or other portalled component. The same className="nested-portal" pattern applies.

Editable example
<Popover
  button={(buttonProps) => (
    <Button type="secondary" {...buttonProps}>
      Item settings
    </Button>
  )}
>
  <Stack gap="s" padding="s">
    <Text>Item configuration</Text>
    <OptionMenu
      className="nested-portal"
      button={<Button type="secondary" decorator={ButtonDecorator.Dropdown}>More actions</Button>}
    >
      <OptionMenuItem>Move up</OptionMenuItem>
      <OptionMenuItem>Move down</OptionMenuItem>
      <OptionMenuSeparator />
      <OptionMenuItem destructive>Delete</OptionMenuItem>
    </OptionMenu>
  </Stack>
</Popover>
<Popover
  button={(buttonProps) => (
    <Button type="secondary" {...buttonProps}>
      Item settings
    </Button>
  )}
>
  <Stack gap="s" padding="s">
    <Text>Item configuration</Text>
    <OptionMenu
      className="nested-portal"
      button={<Button type="secondary" decorator={ButtonDecorator.Dropdown}>More actions</Button>}
    >
      <OptionMenuItem>Move up</OptionMenuItem>
      <OptionMenuItem>Move down</OptionMenuItem>
      <OptionMenuSeparator />
      <OptionMenuItem destructive>Delete</OptionMenuItem>
    </OptionMenu>
  </Stack>
</Popover>

Summary