feat: add isDisabled prop ParallaxProvider to disable the controller #183 (#207)

jscottsmith · web-flow · commit ad55c64e4f19 · 2023-04-03T23:57:58.000-07:00
diff --git a/documentation/docs/usage/components/parallax-provider.md b/documentation/docs/usage/components/parallax-provider.md
@@ -38,6 +38,7 @@ The following props configure the `<ParallaxProvider>` component:
 | ------------------- | :-----------: | :--------- | ------------------------------------------------------------------------------------------------------------------------ |
 | **scrollAxis**      |   `string`    | `vertical` | Optionally pass the scroll axis for setting horizontal/vertical scrolling. One of `vertical` or `horizontal`             |
 | **scrollContainer** | `HTMLElement` | `<body>`   | Optionally set the container that has overflow and will contain parallax elements. Defaults to the document scroll body. |
+| **isDisabled**      |   `boolean`   | `false`    | Disables the ParallaxController and all animations.                                                                      |
 
 ## More Examples
 
@@ -83,3 +84,21 @@ const ScrollContainer = () => {
   );
 };
 ```
+
+### Disabling All Parallax Elements
+
+With the `isDisabled` prop you may disable every parallax element in the provider when a condition is met, instead of individually. This can be helpful to disable parallax in certain situations like on mobile devices, or for users who [prefers-reduced-motion](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion). Elements will be re-enabled when `isDisabled` is `true`.
+
+```tsx
+const App = () => {
+  const userPrefersReducedMotion = useMediaQuery({
+    query: '(prefers-reduced-motion)',
+  });
+
+  return (
+    <ParallaxProvider isDisabled={userPrefersReducedMotion}>
+      {props.children}
+    </ParallaxProvider>
+  );
+};
+```
diff --git a/package.json b/package.json
@@ -92,7 +92,7 @@
     }
   ],
   "dependencies": {
-    "parallax-controller": "^1.5.0"
+    "parallax-controller": "^1.7.0"
   },
   "devDependencies": {
     "@babel/core": "^7.17.8",
diff --git a/src/components/ParallaxProvider/index.test.tsx b/src/components/ParallaxProvider/index.test.tsx
@@ -48,6 +48,41 @@ describe('A <ParallaxProvider>', () => {
     expect(parallaxController).toBeInstanceOf(ParallaxController);
   });
 
+  it('to disable parallax elements and re-enable', () => {
+    let parallaxController: ParallaxController | null = null;
+
+    const ContextChecker = () => {
+      parallaxController = useParallaxController();
+      if (parallaxController) {
+        parallaxController.disableParallaxController = jest.fn();
+        parallaxController.enableParallaxController = jest.fn();
+      }
+      return null;
+    };
+
+    const context = render(
+      <ParallaxProvider isDisabled>
+        <ContextChecker />
+      </ParallaxProvider>
+    );
+
+    expect(
+      // @ts-expect-error
+      parallaxController.disableParallaxController
+    ).toBeCalled();
+
+    context.rerender(
+      <ParallaxProvider>
+        <ContextChecker />
+      </ParallaxProvider>
+    );
+
+    expect(
+      // @ts-expect-error
+      parallaxController.enableParallaxController
+    ).toBeCalled();
+  });
+
   it('to destroy the controller when unmounting', () => {
     const node = document.createElement('div');
 
diff --git a/src/components/ParallaxProvider/index.tsx b/src/components/ParallaxProvider/index.tsx
@@ -20,10 +20,27 @@ export class ParallaxProvider extends Component<ParallaxProviderProps, {}> {
     });
   }
 
+  componentDidMount() {
+    if (this.props.isDisabled) {
+      this.controller?.disableParallaxController();
+    }
+  }
+
   componentDidUpdate(prevProps: ParallaxProviderProps) {
-    if (prevProps.scrollContainer !== this.props.scrollContainer) {
-      // @ts-ignore
-      this.controller.updateScrollContainer(this.props.scrollContainer);
+    if (
+      prevProps.scrollContainer !== this.props.scrollContainer &&
+      this.props.scrollContainer
+    ) {
+      this.controller?.updateScrollContainer(this.props.scrollContainer);
+    }
+
+    if (prevProps.isDisabled !== this.props.isDisabled) {
+      if (this.props.isDisabled) {
+        this.controller?.disableParallaxController();
+      }
+      if (!this.props.isDisabled) {
+        this.controller?.enableParallaxController();
+      }
     }
   }
 
diff --git a/src/components/ParallaxProvider/types.ts b/src/components/ParallaxProvider/types.ts
@@ -11,4 +11,8 @@ export interface ParallaxProviderProps {
    * to the HTML body
    */
   scrollContainer?: HTMLElement;
+  /**
+   * Disables the ParallaxController and all animations.
+   */
+  isDisabled?: boolean;
 }
diff --git a/stories/Container.tsx b/stories/Container.tsx
@@ -1,17 +1,21 @@
-import { ScrollAxis } from 'parallax-controller';
 import React from 'react';
 import { PropsWithChildren } from 'react';
 import { ParallaxProvider } from '../src';
+import { ParallaxProviderProps } from '../src/components/ParallaxProvider/types';
 
 type ContainerProps = PropsWithChildren<{
-  scrollAxis: ScrollAxis;
   className?: string;
-}>;
+}> &
+  ParallaxProviderProps;
 
-export const Container = (props: ContainerProps) => (
-  <ParallaxProvider scrollAxis={props.scrollAxis}>
+export const Container = ({
+  className,
+  children,
+  ...props
+}: ContainerProps) => (
+  <ParallaxProvider {...props}>
     <div className={props.scrollAxis}>
-      <div className={props.className}>{props.children}</div>
+      <div className={className}>{children}</div>
     </div>
   </ParallaxProvider>
 );
diff --git a/stories/Parallax/1_ParallaxVertical.stories.tsx b/stories/Parallax/1_ParallaxVertical.stories.tsx
@@ -215,6 +215,32 @@ export const WithAHundredElements = () => {
   );
 };
 
+export const WithParallaxElementsGloballyDisabled = (args) => {
+  const amount = 100;
+  const elements = new Array(amount).fill(null).map((x, i) => i);
+
+  return (
+    <Container scrollAxis="vertical" isDisabled={args.isDisabled}>
+      <div className={styles.elements}>
+        {elements.map((_, i) => {
+          const props: ParallaxProps = propConfigs[i % propConfigs.length];
+          return (
+            <div key={i} className={styles.small} style={{ perspective: 800 }}>
+              <Parallax {...props}>
+                <Element name={i + 1} />
+              </Parallax>
+            </div>
+          );
+        })}
+      </div>
+    </Container>
+  );
+};
+
+WithParallaxElementsGloballyDisabled.args = {
+  isDisabled: true,
+};
+
 export const InsideADiv = () => {
   const amount = 2;
   const offA = -50;
diff --git a/yarn.lock b/yarn.lock
@@ -11140,10 +11140,10 @@ pako@~1.0.5:
   resolved "https://registry.yarnpkg.com/pako/-/pako-1.0.11.tgz#6c9599d340d54dfd3946380252a35705a6b992bf"
   integrity sha512-4hLB8Py4zZce5s4yd9XzopqwVv/yGNhV1Bl8NTmCq1763HeK2+EwVTv+leGeL13Dnh2wfbqowVPXCIO0z4taYw==
 
-parallax-controller@^1.5.0:
-  version "1.5.0"
-  resolved "https://registry.yarnpkg.com/parallax-controller/-/parallax-controller-1.5.0.tgz#324859f336566f114b8c08212b8454b6ad17de0f"
-  integrity sha512-X7FKD0bH27hJHdknH/UNEznmw6xjcWz/QA4M6RLlE/gUXfbePKhk+ld/20e58aAfjMqj+Q7RURryISFcDIVmtA==
+parallax-controller@^1.7.0:
+  version "1.7.0"
+  resolved "https://registry.yarnpkg.com/parallax-controller/-/parallax-controller-1.7.0.tgz#659e8176922034ac548009ac544951432330aa0a"
+  integrity sha512-tIU/LgH9oIrvC6o+rvGQis8/NXxsHNuF5LODmcc5TjvEDUi2qiR/iisFmyaqI9LImQ3psdAv28k2ZEAnFekiig==
   dependencies:
     bezier-easing "^2.1.0"
 

Original file line number	Diff line number	Diff line change
`@@ -92,7 +92,7 @@`
`92`	`92`	`}`
`93`	`93`	`],`
`94`	`94`	`"dependencies": {`
`95`		`- "parallax-controller": "^1.5.0"`
	`95`	`+ "parallax-controller": "^1.7.0"`
`96`	`96`	`},`
`97`	`97`	`"devDependencies": {`
`98`	`98`	`"@babel/core": "^7.17.8",`
Original file line number	Diff line number	Diff line change
`@@ -11,4 +11,8 @@ export interface ParallaxProviderProps {`
`11`	`11`	`* to the HTML body`
`12`	`12`	`*/`
`13`	`13`	`scrollContainer?: HTMLElement;`
	`14`	`+ /**`
	`15`	`+ * Disables the ParallaxController and all animations.`
	`16`	`+ */`
	`17`	`+ isDisabled?: boolean;`
`14`	`18`	`}`