Setup components for a custom environment like IFrames, Shadow DOM or an Electron context.

No preview available for environment


Internally, we use Zag.js, which uses DOM query methods like document.querySelectorAll and document.getElementById to locate elements within the machine.

In custom environments like iframe, Shadow DOM, Electron, etc., the machine might not work as expected because document may not be available.

To provide the correct reference to root node or document, you can pass getRootNode function either to all Ark UI root components, or provide a default with this Environment component.

In shadow DOM, the root node can be derived from calling element.getRootNode() method on any element.


When targeting a custom environment like an iframe, Shadow DOM or Electron, you can render the Environment component to provide the environment context to all Ark UI child components.

import { Environment, useEnvironmentContext } from '@ark-ui/react'
import { useCallback, type ReactNode } from 'react'

export const App = (props: { children: ReactNode }) => {
  const getRootNode = useCallback(() => document, [])
  return (
    <Environment.Root value={getRootNode}>{props.children}</Environment.Root>

Consuming the environment context

You can use the useEnvironmentContext hook to consume the environment context.

It will return undefined by default, if the Environment component is not rendered as a parent.

const getRootNode = useEnvironmentContext()