Note:
Only use this package for managing elevation of components that are renderred outside of normal HTML flow i.e component renderred to the root of the document.
App developers should rarely use this package, it's mainly for Balance internals.

Elevate

The Elevate component bumps the elevation modifier of its children. The elevation modifier can be accessed through the useElevationModifier hook or be directly applied by passing the zIndex value to the useElevate hook. Elevate components can be nested in themselves.

The elevation modifiers are automatically applied to elevation tokens from the theme but must be manually applied to any custom zIndex values.

Usage

Below is a demonstration(through values) of how elevation changes are applied.

Edit in Playroom

const SomeComponentThatRendersToRoot = () => {
  // The elevation from theme has already been modified based on context
  const { elevation } = useTheme();
  const elevationModifier = useElevationModifier();
  // Custom elevation has to be modified manually based on context.
  // You can either use the useElevate hook or manually add the elevation modifier above to your zIndex.
  const { zIndex } = useElevate({ zIndex: 50 });
  return (
    <Card>
      <Stack>
        <Text>
          <Strong>SomeComponentThatRendersToRoot</Strong>
        </Text>
        <div>zIndex modifier: {elevationModifier}</div>
        <div>Dropdown zIndex: {elevation.dropdown}</div>
        <div>Custom zIndex: {zIndex}</div>
      </Stack>
    </Card>
  );
};
const WrapperThatElevates = ({ children }: { children: React.ReactNode }) => {
  return (
    <Elevate>
      <Stack>
        <Text>
          <Strong>WrapperThatElevates</Strong>, my children's zIndex modifier
          should be higher than above.
        </Text>
        <Box paddingLeft="xlarge">{children}</Box>
      </Stack>
    </Elevate>
  );
};
return (
  <Stack gap="large">
    {/** This component is not elevated so its elevation modifier should be zero */}
    <SomeComponentThatRendersToRoot />
    <WrapperThatElevates>
      {/** This component is elevated so its elevation modifier should be non-zero */}
      <SomeComponentThatRendersToRoot />
      <WrapperThatElevates>
        {/** This component has nested elevation so its elevation modifier should be a sum of previous elevation modifiers */}
        <SomeComponentThatRendersToRoot />
        <WrapperThatElevates>
          <SomeComponentThatRendersToRoot />
        </WrapperThatElevates>
      </WrapperThatElevates>
    </WrapperThatElevates>
  </Stack>
);

Dropdowns and drawers

In our theme, Dropdowns have a lower elevation than Drawers which means a dropdown will always appear under a drawer. But what about a Dropdown inside a drawer? It appearing under the drawer doesn't seem correct. So BAL internally elevates the Drawer body which results in the Drawer's children always appearing above it.

Edit in Playroom

const [isOpen, setIsOpen] = useState(false);
return (
  <React.Fragment>
    <Button label="Open drawer" onClick={() => setIsOpen(true)} />
    <SideDrawerController isOpen={isOpen} onClose={() => setIsOpen(false)}>
      <SideDrawer>
        <SideDrawer.Body>
          <Box padding="large">
            <Dropdown>
              <Dropdown.Trigger>
                <Dropdown.TriggerButton label="Open dropdown" />
              </Dropdown.Trigger>
              <Dropdown.Item onSelect={() => alert('Selected item 1')}>
                Item 1
              </Dropdown.Item>
              <Dropdown.Item onSelect={() => alert('Selected item 2')}>
                Item 2
              </Dropdown.Item>
              <Dropdown.Item onSelect={() => alert('Selected item 3')}>
                Item 3
              </Dropdown.Item>
            </Dropdown>
          </Box>
        </SideDrawer.Body>
      </SideDrawer>
    </SideDrawerController>
  </React.Fragment>
);

Nested drawers and toasts

Toasts should appear above all other elements regardless of their relative elevation. In the below example we see that a toast can be opened in the parent drawer that appears on top of the nested drawer when opened.

Edit in Playroom

const NestedDrawer = ({ onClose }: { onClose: () => void }) => {
  const toast = useToasts();
  const showToast = () => {
    toast.addToast({
      title: 'toast',
      message: 'Toast Toast Toast Toast Toast Toast ',
      preserve: true,
    });
  };
  return (
    <SideDrawer>
      <SideDrawer.Header>
        <SideDrawer.Title>Nested drawer</SideDrawer.Title>
      </SideDrawer.Header>
      <SideDrawer.Body>
        <Stack gap="large" padding="xlarge">
          <Button label="Show toast" onClick={showToast} />
        </Stack>
      </SideDrawer.Body>
      <SideDrawer.Footer>
        <Button label="Done" onClick={onClose} />
      </SideDrawer.Footer>
    </SideDrawer>
  );
};
const [isParentOpen, toggleIsParentOpen] = React.useReducer(
  (bool) => !bool,
  false
);
const [isChildOpen, toggleIsChildOpen] = React.useReducer(
  (bool) => !bool,
  false
);
const toast = useToasts();
const showToast = () => {
  toast.addToast({
    title: 'toast',
    message: 'Toast Toast Toast Toast Toast Toast ',
    preserve: true,
  });
};
return (
  <>
    <Button label="Open side drawer" onClick={toggleIsParentOpen} />
    <SideDrawerController isOpen={isParentOpen} onClose={toggleIsParentOpen}>
      <SideDrawer>
        <SideDrawer.Header>
          <SideDrawer.Title>Parent drawer</SideDrawer.Title>
        </SideDrawer.Header>
        <SideDrawer.Body>
          <Stack gap="large" padding="xlarge">
            <Button label="Show toast" onClick={showToast} />
            <Button label="Open nested drawer" onClick={toggleIsChildOpen} />
            <SideDrawerController
              isOpen={isChildOpen}
              onClose={toggleIsChildOpen}
            >
              <NestedDrawer onClose={toggleIsChildOpen} />
            </SideDrawerController>
          </Stack>
        </SideDrawer.Body>
        <SideDrawer.Footer>
          <Button label="Done" onClick={toggleIsParentOpen} />
        </SideDrawer.Footer>
      </SideDrawer>
    </SideDrawerController>
  </>
);