@nikxda/react-xray v2.0.0
react-xray
Accessible image component that reveals images on user interaction
Installation
npm install @nikxda/react-xrayTry it online
The storybook is available here: https://react-xray.vercel.app/
Preview
Features
- :gear: Fully customizable
- :tophat: TypeScript support built in
- :sparkles: Custom
feColorMatrixeffects - :computer: Responsive out of the box
- :iphone: Touch support
- :eyeglasses: Basic accessibility built-in
- :tada: Custom transitions
- :mag: Zoom mode
- :100: 3KB minified and gzip-ed
Usage
import XRay from '@nikxda/react-xray';
const ExampleComponent = () => (
<div>
<h1>An Example Image</h1>
<XRay href="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