Nasal Piercings Manipulator

    @halka/react-medium-zoom
    TypeScript icon, indicating that this package has built-in type declarations

    0.1.1 • Public • Published

    @halka/react-medium-zoom

    Bundle Size npm version types license

    A thin wrapper on top of the amazing Medium Zoom


    Why the wrapper?

    Got tired of re-writing this component everywhere. It tried to strike the right balance between the declarative goodness and imperative power.

    Feel free to star the repo, fork the repo and raise issues


    Installation

    npm i @halka/react-medium-zoom

    API Reference

    <MediumZoom> component

    The easiest way to consume this package is using the MediumZoom component

    import { MediumZoom } from '@halka/react-medium-zoom';
    
    function App() {
      return (
        <div>
          <OtherComponents >
          <MediumZoom
            /** you can also attach a ref and it will be refer to the <img> element underneath
            /** any valid <img /> props **/
            src={imgUrl}
            alt="image"
            style={{ width: 'auto', height: 400 }}
            /** anything you can pass to medium zoom options **/
            options={{ background: 'black', margin: 20 }}
          />
          <OtherComponents >
        </div>
      );
    }

    Props

    • All the base <img /> props like src, alt (don't forget alt), etc.
    • You can also use ref to attach a ref to the original <img> component
    • options - An object that accepts all the options accepted by medium-zoom. Reference docs
    • You can also add data-zoom-src to add a higher quality image for the zoomed view. Reference docs

    Supported Options

    Property Type Default Description
    margin number 0 The space outside the zoomed image
    background string "#fff" The background of the overlay
    scrollOffset number 40 The number of pixels to scroll to close the zoom
    container string | HTMLElement | object null The viewport to render the zoom in
    Read more →
    template string | HTMLTemplateElement null The template element to display on zoom
    Read more →


    useMediumZoom hook

    If you want more control over the interaction, you can use the hook as well.

    import { useMediumZoom } from '@halka/react-medium-zoom';
    
    function Image(props) {
      const ref = React.useRef();
      const handler = useMediumZoom(ref, {
        background: 'black',
      });
    
      return (
        <div>
          <button
            onClick={() => {
              handler.open();
            }}
          >
            Open Image
          </button>
          <img ref={ref} src={imgUrl} alt="image" />
        </div>
      );
    }

    Arguments

    • ref - first arguments is the ref object of the <img> element to attach to.
    • options - second is the options object accepted by medium-zoom. Reference docs

    The hook returns the handler object which exposes a subset of the methods present on zoom instance.


    handler object

    We strongly recommend not using the imperative methods on the zoom instance directly and use the methods exposed on the handler object instead.


    open(): Promise<void>

    Opens the zoom and returns a promise resolving with the zoom.

    handler.open();

    Emits an event open on animation start and opened when completed.

    Reference docs

    Note: the return type is void instead of the zoom instance and it doesn't accept a target


    close(): Promise<void>

    Closes the zoom and returns a promise resolving with the zoom.

    handler.close();

    Emits an event close on animation start and closed when completed.

    Reference docs

    Note: the return type is void instead of the zoom instance


    toggle(): Promise<void>

    Opens the zoom when closed / dismisses the zoom when opened, and returns a promise resolving with the zoom.

    handler.toggle();

    Reference docs

    Note: the return type is void instead of the zoom instance and it doesn't accept a target.


    on(type: string, listener: () => void, options?: boolean | AddEventListenerOptions): void

    Registers the listener on each target of the zoom.

    The same options as addEventListener are used.

    handler.on('closed', event => {
      // the image has been closed
    });
    
    handler.on(
      'open',
      event => {
        // the image has been opened (tracked only once)
      },
      { once: true }
    );

    Reference docs

    Note: the return type is void instead of the zoom instance


    off(type: string, listener: () => void, options?: boolean | AddEventListenerOptions): void

    Removes the previously registered listener on each target of the zoom.

    The same options as removeEventListener are used.

    function listener(event) {
      // ...
    }
    
    handler.on('open', listener);
    // ...
    handler.off('open', listener);

    Reference docs

    Note: the return type is void instead of the zoom instance


    Supported Events

    Event Description
    open Fired immediately when the open method is called
    opened Fired when the zoom has finished being animated
    close Fired immediately when the close method is called
    closed Fired when the zoom out has finished being animated
    detach Fired when the detach method is called
    update Fired when the update method is called

    Reference docs

    Example and Advance Usage

    • /examples/Image.tsx - showcases some advance usecases using the useMediumZoom hook. It shows usage of handler object, adding custom event listeners and using template.

    You can also refer to examples in medium-zoom repo and try to implement using them the ways shown in the example component mentioned above.

    Install

    npm i @halka/react-medium-zoom

    DownloadsWeekly Downloads

    7

    Version

    0.1.1

    License

    MIT

    Unpacked Size

    221 kB

    Total Files

    15

    Last publish

    Collaborators

    • drenther
    • pepsighan