@halka/react-medium-zoom
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 likesrc
,alt
(don't forgetalt
), etc. - You can also use
ref
to attach aref
to the original<img>
component -
options
- An object that accepts all the options accepted bymedium-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 theref
object of the<img>
element to attach to. -
options
- second is the options object accepted bymedium-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.
Note: the return type is
void
instead of the zoom instance and it doesn't accept atarget
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.
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();
Note: the return type is
void
instead of the zoom instance and it doesn't accept atarget
.
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 }
);
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);
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 |
Example and Advance Usage
-
/examples/Image.tsx
- showcases some advance usecases using theuseMediumZoom
hook. It shows usage ofhandler
object, adding customevent
listeners and usingtemplate
.
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.