found-scroll
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.0 • Public • Published

    Found Scroll npm

    Scroll management for Found.

    Usage

    import { createBrowserRouter, createRender } from 'found';
    import { ScrollManager } from 'found-scroll';
    
    /* ... */
    
    const render = createRender({ renderError });
    
    const BrowserRouter = createBrowserRouter({
      routeConfig,
    
      render: (renderArgs) => (
        <ScrollManager renderArgs={renderArgs}>{render(renderArgs)}</ScrollManager>
      ),
    });

    Guide

    Installation

    $ npm i -S react found
    $ npm i -S found-scroll
    

    Basic usage

    When constructing a router, in the render method, wrap the rendered element with <ScrollManager>, and pass in renderArgs as a prop, as in the above example.

    Scrollable Containers

    Generally only the window scroll position is restored for a location. For cases where you also want to restore alternative scroll container there is useScrollContainer

    import { useScrollContainer } from 'found-scroll';
    
    function MyScrollView() {
      const scrollRef = useScrollContainer('my-scroll-view');
    
      return <div ref={scrollRef} />;
    }

    Scroll containers are identified with a 'scrollKey'. There should only be one element associated with a given key for any given location. Think of it as similar to React's key prop, in that it provides a stable identity for an element across renders.

    Custom scroll behavior

    You can provide a custom shouldUpdateScroll callback as a prop to <ScrollManager>. This callback receives the previous and the current renderArgs.

    The callback can return:

    • a falsy value to suppress updating the scroll position
    • a position array of x and y, such as [0, 100], to scroll to that position
    • a string with the id or name of an element, to scroll to that element
    • a truthy value to emulate the browser default scroll behavior
    const shouldUpdateScrollByPathname = (prevRenderArgs, { location }) =>
      !prevRenderArgs || location.pathname !== prevRenderArgs.location.pathname;
    
    const shouldUpdateScrollByRoute = (prevRenderArgs, { routes }) => {
      if (routes.some((route) => route.ignoreScrollBehavior)) {
        return false;
      }
    
      if (routes.some((route) => route.scrollToTop)) {
        return [0, 0];
      }
    
      return true;
    };
    
    const render = (renderArgs) => (
      <ScrollManager
        shouldUpdateScroll={shouldUpdateScrollByPathname}
        renderArgs={renderArgs}
      >
        {/* ... */}
      </ScrollManager>
    );

    You can customize <ScrollManager> even further by providing a createScrollBehavior callback that creates the scroll behavior object. This allows using a custom subclass of ScrollBehavior from scroll-behavior with custom logic. When using a custom createScrollBehavior callback, you can continue to specify the shouldUpdateScroll callback as above.

    const render = (renderArgs) => (
      <ScrollManager
        createScrollBehavior={(config) => new MyScrollBehavior(config)}
        renderArgs={renderArgs}
      >
        {/* ... */}
      </ScrollManager>
    );

    Install

    npm i found-scroll

    DownloadsWeekly Downloads

    2,336

    Version

    1.1.0

    License

    MIT

    Unpacked Size

    20.1 kB

    Total Files

    16

    Last publish

    Collaborators

    • monastic.panic
    • itajaja
    • sloria
    • everes
    • taion