useZoom

Add scroll-based zoom functionality to any <img /> element.

Import

import { useZoom } from '@hoverinc/design-system-react-web';

Options

Option	Type	Default	Description
`zoom`	`number`	`0.1`	Zoom factor applied on each scroll event (controls the speed of the zoom)
`maxZoom`	`number \| false`	`false`	Maximum zoom level allowed (e.g: `5` maxes out the image at 5 times the original size)
`initialZoom`	`number`	`1`	Initial zoom level (use in combination with `initialX` and `initialY` to zoom to specific region of the image)
`initialX`	`number`	`0.5`	Initial horizontal offset (for use with `initialZoom`)
`initialY`	`number`	`0.5`	Initial horizontal offset (for use with `initialZoom`)

ZoomOptions props

Import the ZoomOptions type to incorporate zoom options into your component's props.

import { Image, ImageProps } from '@hoverinc/design-system-react-web';
import type { ZoomOptions } from '@hoverinc/design-system-react-web';
interface ZoomImageProps extends ImageProps {
  zoomOptions?: ZoomOptions;
}
export const ZoomImage = ({ zoomOptions, ...props }: ZoomImageProps) => {
  const { props } = useZoom({ maxZoom: 10, ...zoomOptions });
  return <Image cursor="zoom-in" {...props} />;
};

Usage

Simply spread the returned props object into the target image element. Note that the props object includes a ref that is required for zoom to work so be careful not to overwrite it.

live

() => {
  const { props } = useZoom({ maxZoom: 10 });
  return (
    <Image
      alt="Black modern house for zoom example"
      src="/images/documentation/example-house.png"
      width="700"
      cursor="zoom-in"
      {...props}
    />
  );
};

Resize

If it's possible that the image element's size will change, you'll need to call resize. Depending on what triggers the resize, you can use the resize event on window, a ResizeObserver like @chakra-ui/react-use-size's useSize hook, or another handler that you know will cause a resize.

Window resize

Here we're using vw units so we know a window resize will always resize the image.

live

() => {
  const { props, resize } = useZoom({ maxZoom: 10 });
  useEffect(() => {
    window.addEventListener('resize', resize);
    return () => window.removeEventListener('resize', resize);
  }, [resize]);
  return (
    <Image
      alt="Black modern house for zoom example"
      src="/images/documentation/example-house.png"
      width="30vw"
      cursor="zoom-in"
      {...props}
    />
  );
};

Breakpoint

Here we're using responsive style prop width and an effect depending on the value of the useBreakpoint hook to trigger a resize when the breakpoint changes.

live

() => {
  const breakpoint = useBreakpoint();
  const { props, resize } = useZoom({ maxZoom: 10 });
  useEffect(resize, [breakpoint]);
  return (
    <Image
      alt="Black modern house for zoom example"
      src="/images/documentation/example-house.png"
      width={{ base: '600', tablet: '700', desktop: '750' }}
      cursor="zoom-in"
      {...props}
    />
  );
};

Handler

Here we're resizing the image in an event handler so we can just invoke resize() in the same handler.

live

() => {
  const [width, setWidth] = useState(450);
  const { props, resize } = useZoom({ maxZoom: 10 });
  return (
    <Stack spacing="300">
      <Slider
        min={300}
        max={600}
        value={width}
        onChange={value => {
          setWidth(value);
          resize();
        }}
      />
      <Image
        alt="Black modern house for zoom example"
        src="/images/documentation/example-house.png"
        width={`${width}px`}
        cursor="zoom-in"
        {...props}
      />
    </Stack>
  );
};

Set Zoom

The useZoom hook returns the current zoomRatio and a setZoom method. This enables consumers of the hook to build custom UI zoom controls.

live

() => {
  const {
    props,
    state: { zoomRatio },
    setZoom,
  } = useZoom({ maxZoom: 2.0 });
  return (
    <Stack spacing="300">
      <Slider
        min={1.0}
        max={2.0}
        step={0.1}
        onChange={value => setZoom(value)}
        value={zoomRatio}
        width="30vw"
      />
      <Image
        cursor="zoom-in"
        alt="Black modern house for zoom example"
        src="/images/documentation/example-house.png"
        {...props}
      />
    </Stack>
  );
};

Focus Box

The useZoom hook returns a focusBox method. The focusBox receives a bounding box parameter and zooms and centers the bounding box as much as possible while still respecting maxZoom.

The bounding box is defined using the natural dimensions of the image. The natural dimensions are adjusted as needed by the useZoom hook to account for differences between the natural dimensions and the dimensions of the image on screen.

The maxZoom option can be passed to focusBox if a lower maxZoom is desired. Passing a maxZoom higher than the maxZoom passed to useZoom is ignored.

live

() => {
  const { props, focusBox, setZoom } = useZoom({ maxZoom: 8.0 });
  const focusLeftEye = {
    x: 631,
    y: 621,
    width: 289,
    height: 223,
  };
  return (
    <Stack spacing="300">
      <HStack>
        <Button onClick={() => setZoom(1.0)}>Reset</Button>
        <Button onClick={() => focusBox(focusLeftEye, { maxZoom: 2.0 })}>
          Left Eye (2.0)
        </Button>
        <Button onClick={() => focusBox(focusLeftEye)}>Left Eye (8.0)</Button>
      </HStack>
      <Image
        alt="Black modern house for zoom example"
        cursor="zoom-in"
        src="/images/documentation/example-house.png"
        {...props}
      />
    </Stack>
  );
};

useTheme

CSS Variables

Design System

Settings

useZoom

Import

Options

ZoomOptions props

Usage

Resize

Window resize

Breakpoint

Handler

Set Zoom

Focus Box