Skip to content

Latest commit

 

History

History
86 lines (65 loc) · 4.03 KB

README.md

File metadata and controls

86 lines (65 loc) · 4.03 KB
Raw

react-xray

Accessible image component that reveals images on user interaction

Installation

npm install @nikxda/react-xray

Try it online

The storybook is available here: https://react-xray.vercel.app/

Preview

React XRay

Features

  • ⚙️  Fully customizable
  • 🎩  TypeScript support built in
  • ✨  Custom feColorMatrix effects
  • 💻  Responsive out of the box
  • 📱  Touch support
  • 👓  Basic accessibility built-in
  • 🎉  Custom transitions
  • 🔍  Zoom mode
  • 💯  3KB minified and gzip-ed

Usage

import XRay from '@nikxda/react-xray';

const ExampleComponent = () => (
 <div>
  <h1>An Example Image</h1>
  <XRay src="http://picsum.photos/1920/1080" alt="Lorem Picsum" />
 </div>
)

Component Props

The following properties are available:

Prop Name Type Default Value Description Required
href string - The image URL. Yes
alt string - A description of the image. Yes
blur number 15 The amount of blur. No
radiusScale number 1 The factor by which to scale the default responsive radius. No
fixedRadius number null If no responsive radius is desired, a fixed radius can be applied. No
onClick function ()=>{} An onClick handler. No
effects string[] [] Effects to be applied globally, see Effects. No
imageLayerEffects string[] [] Effects to be applied to the image layer, see Effects. No
blurLayerEffects string[] [] Effects to be applied to the blur layer, see Effects. No
circleInTransition string "elastic.out(1, 0.3)" The GSAP transition which will be used to transition the circle in. No
circleInDuration number 0.5 The duration of the circleInTransition No
circleOutTransition string "expo.out" The GSAP transition which will be used to transition the circle out. No
circleOutDuration number 0.2 The duration of the circleOutTransition No
canReveal boolean true Whether the revealed state can be toggled using the keyboard on focus. No
autoReveal boolean false Whether the image should automatically reveal itself upon focus. No
persistReveal boolean false Whether the image should stay visible after it has been revealed for the first time. No
zoom number 1 The amount of zoom. No

Effects

XRay supports custom effects on three layers:

  • The global layer effects are applied to the whole component, therefore affecting all visuals. The corresponding property is effects.
  • The image layer effects are applied only to the revealed image, therefore to what is visible in the circular cutout. The corresponding property is imageLayerEffects.
  • The blur layer effects are applied only to the blurred section of the image. The corresponding property is blurLayerEffects.

Each of the three proprties take a string[] with each entry of the array being an effect matrix as per the MDN specification found here. For example, to darken the blurry part of the image, one may supply the value [".3 0 0 0 0 0 .3 0 0 0 0 0 .3 0 0 0 0 0 1 0"] for blurLayerEffects.

Accessibility & Responsiveness

React XRay provides basic accessibility out of the box. It features touch support for mobile devices and will allow the image to be revealed when the element has the focus and the mouse is not currently over the image. In this case, the component will display a message saying that the image can be revealed by pressing space. The responsiveness comes from the fact that a single radius given in pixels will likely not be suitable for all screen sizes. XRay therefore calculates a "responsive" radius by tracking the wrapper dimensions. The default diameter of the circular cutout is half the length of the shorter side. If this choice is not suitable, the responsive radius can be scaled using radiusScale or set to a fixed value using fixedRadius.

License

MIT