feat(accordion): add transitionDuration and scrollOnOpen props

Author: KMNowak

.changeset/shy-kiwis-bake.md

@@ -0,0 +1,6 @@
+---
+"@heroui/accordion": patch
+---
+
+- Introduce new prop `scrollOnOpen?: boolean` to automatically scroll to the content when expanded
+- Introduce new prop `transitionDuration?: number` to customize animation speed. Defaults to 300ms as it is right now

packages/components/accordion/__tests__/accordion.test.tsx

@@ -438,4 +438,66 @@ describe("Accordion", () => {
 
     expect(getByRole("separator")).toHaveClass("bg-rose-500");
   });
+
+  it("should scroll to content when scrollOnOpen is true", async () => {
+    const scrollIntoViewMock = jest.fn();
+
+    Element.prototype.scrollIntoView = scrollIntoViewMock;
+
+    const wrapper = render(
+      <Accordion scrollOnOpen>
+        <AccordionItem key="1" data-testid="item-1" title="Accordion Item 1">
+          Accordion Item 1 description
+        </AccordionItem>
+      </Accordion>,
+    );
+
+    const first = wrapper.getByTestId("item-1");
+    const firstButton = first.querySelector("button") as HTMLElement;
+
+    await user.click(firstButton);
+
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    });
+
+    expect(scrollIntoViewMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        behavior: "smooth",
+        block: "nearest",
+      }),
+    );
+
+    jest.restoreAllMocks();
+  });
+
+  it("should apply custom transition duration", async () => {
+    const customDuration = 500;
+    const wrapper = render(
+      <Accordion disableAnimation={false} transitionDuration={customDuration}>
+        <AccordionItem key="1" data-testid="item-1" title="Accordion Item 1">
+          Accordion Item 1 description
+        </AccordionItem>
+      </Accordion>,
+    );
+
+    const first = wrapper.getByTestId("item-1");
+    const firstButton = first.querySelector("button") as HTMLElement;
+
+    await user.click(firstButton);
+
+    const content = first.querySelector("section");
+
+    expect(content).toBeInTheDocument();
+    // During animation the opacity changes from 0 to 1, reaching number close to 1 on the end
+    expect(content).toHaveAttribute("style", expect.stringMatching("opacity: 0"));
+
+    // Allow framer-motion time to apply animation styles
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, customDuration + 10));
+    });
+
+    // Match opacity values between 0.98 and 1 (inclusive)
+    expect(content).toHaveAttribute("style", expect.stringMatching(/opacity: (0\.9[8-9]\d*|1)/));
+  });
 });

packages/components/accordion/src/accordion-item.tsx

@@ -1,9 +1,9 @@
 import type {Variants} from "framer-motion";
-import type {ReactNode} from "react";
 import type {UseAccordionItemProps} from "./use-accordion-item";
+import type {ReactNode} from "react";
 
 import {forwardRef} from "@heroui/system";
-import {useMemo} from "react";
+import {useMemo, useRef, useEffect} from "react";
 import {ChevronIcon} from "@heroui/shared-icons";
 import {AnimatePresence, LazyMotion, m, useWillChange} from "framer-motion";
 import {TRANSITION_VARIANTS} from "@heroui/framer-utils";
@@ -31,6 +31,8 @@ const AccordionItem = forwardRef<"button", AccordionItemProps>((props, ref) => {
     keepContentMounted,
     disableAnimation,
     motionProps,
+    scrollOnOpen,
+    transitionDuration,
     getBaseProps,
     getHeadingProps,
     getButtonProps,
@@ -41,6 +43,22 @@ const AccordionItem = forwardRef<"button", AccordionItemProps>((props, ref) => {
   } = useAccordionItem({...props, ref});
 
   const willChange = useWillChange();
+  const contentRef = useRef<HTMLDivElement>(null);
+
+  // Handle scrolling to content when opened
+  useEffect(() => {
+    if (isOpen && scrollOnOpen && contentRef.current) {
+      const content = contentRef.current;
+
+      // Wait for animation to start
+      setTimeout(() => {
+        content.scrollIntoView({
+          behavior: "smooth",
+          block: "nearest",
+        });
+      }, 50);
+    }
+  }, [isOpen, scrollOnOpen]);
 
   const indicatorContent = useMemo<ReactNode>(() => {
     if (typeof indicator === "function") {
@@ -57,15 +75,33 @@ const AccordionItem = forwardRef<"button", AccordionItemProps>((props, ref) => {
   const content = useMemo(() => {
     if (disableAnimation) {
       if (keepContentMounted) {
-        return <div {...getContentProps()}>{children}</div>;
+        return (
+          <div ref={contentRef} {...getContentProps()}>
+            {children}
+          </div>
+        );
       }
 
-      return isOpen && <div {...getContentProps()}>{children}</div>;
+      return (
+        isOpen && (
+          <div ref={contentRef} {...getContentProps()}>
+            {children}
+          </div>
+        )
+      );
     }
 
     const transitionVariants: Variants = {
-      exit: {...TRANSITION_VARIANTS.collapse.exit, overflowY: "hidden"},
-      enter: {...TRANSITION_VARIANTS.collapse.enter, overflowY: "unset"},
+      exit: {
+        ...TRANSITION_VARIANTS.collapse.exit,
+        overflowY: "hidden",
+        transition: {duration: transitionDuration ? transitionDuration / 1000 : 0.3},
+      },
+      enter: {
+        ...TRANSITION_VARIANTS.collapse.enter,
+        overflowY: "unset",
+        transition: {duration: transitionDuration ? transitionDuration / 1000 : 0.3},
+      },
     };
 
     return keepContentMounted ? (
@@ -82,7 +118,9 @@ const AccordionItem = forwardRef<"button", AccordionItemProps>((props, ref) => {
           }}
           {...motionProps}
         >
-          <div {...getContentProps()}>{children}</div>
+          <div ref={contentRef} {...getContentProps()}>
+            {children}
+          </div>
         </m.section>
       </LazyMotion>
     ) : (
@@ -101,13 +139,15 @@ const AccordionItem = forwardRef<"button", AccordionItemProps>((props, ref) => {
               }}
               {...motionProps}
             >
-              <div {...getContentProps()}>{children}</div>
+              <div ref={contentRef} {...getContentProps()}>
+                {children}
+              </div>
             </m.section>
           </LazyMotion>
         )}
       </AnimatePresence>
     );
-  }, [isOpen, disableAnimation, keepContentMounted, children, motionProps]);
+  }, [isOpen, disableAnimation, keepContentMounted, children, motionProps, transitionDuration]);
 
   return (
     <Component {...getBaseProps()}>

packages/components/accordion/src/use-accordion-item.ts

@@ -42,6 +42,16 @@ export interface Props<T extends object> extends HTMLHeroUIProps<"div"> {
    * Callback fired when the focus state changes.
    */
   onFocusChange?: (isFocused: boolean, key?: React.Key) => void;
+  /**
+   * Whether to automatically scroll to the content when expanded.
+   * @default false
+   */
+  scrollOnOpen?: boolean;
+  /**
+   * Custom duration for the expand/collapse animation in milliseconds.
+   * @default 300
+   */
+  transitionDuration?: number;
 }
 
 export type UseAccordionItemProps<T extends object = {}> = Props<T> &
@@ -71,6 +81,8 @@ export function useAccordionItem<T extends object = {}>(props: UseAccordionItemP
     disableAnimation = globalContext?.disableAnimation ?? false,
     keepContentMounted = false,
     disableIndicatorAnimation = false,
+    scrollOnOpen = false,
+    transitionDuration = 300,
     HeadingComponent = as || "h2",
     onPress,
     onPressStart,
@@ -276,6 +288,8 @@ export function useAccordionItem<T extends object = {}>(props: UseAccordionItemP
     keepContentMounted,
     disableAnimation,
     motionProps,
+    scrollOnOpen,
+    transitionDuration,
     getBaseProps,
     getHeadingProps,
     getButtonProps,

packages/components/accordion/src/use-accordion.ts

@@ -47,6 +47,16 @@ interface Props extends HTMLHeroUIProps<"div"> {
    * The accordion items classNames.
    */
   itemClasses?: AccordionItemProps["classNames"];
+  /**
+   * Whether to automatically scroll to the content when an accordion item is expanded.
+   * @default false
+   */
+  scrollOnOpen?: boolean;
+  /**
+   * Custom duration for the expand/collapse animation in milliseconds.
+   * @default 300
+   */
+  transitionDuration?: number;
 }
 
 export type UseAccordionProps<T extends object = {}> = Props &
@@ -73,6 +83,8 @@ export type ValuesType<T extends object = {}> = {
   keepContentMounted?: Props["keepContentMounted"];
   disableIndicatorAnimation?: AccordionItemProps["disableAnimation"];
   motionProps?: AccordionItemProps["motionProps"];
+  scrollOnOpen?: boolean;
+  transitionDuration?: number;
 };
 
 export function useAccordion<T extends object>(props: UseAccordionProps<T>) {
@@ -105,6 +117,8 @@ export function useAccordion<T extends object>(props: UseAccordionProps<T>) {
     disableAnimation = globalContext?.disableAnimation ?? false,
     disableIndicatorAnimation = false,
     itemClasses,
+    scrollOnOpen = false,
+    transitionDuration = 300,
     ...otherProps
   } = props;
 
@@ -197,6 +211,8 @@ export function useAccordion<T extends object>(props: UseAccordionProps<T>) {
       disableAnimation,
       keepContentMounted,
       disableIndicatorAnimation,
+      scrollOnOpen,
+      transitionDuration,
     }),
     [
       focusedKey,
@@ -211,6 +227,8 @@ export function useAccordion<T extends object>(props: UseAccordionProps<T>) {
       state.expandedKeys.size,
       state.disabledKeys.size,
       motionProps,
+      scrollOnOpen,
+      transitionDuration,
     ],
   );
 
@@ -246,6 +264,8 @@ export function useAccordion<T extends object>(props: UseAccordionProps<T>) {
     disableAnimation,
     handleFocusChanged,
     itemClasses,
+    scrollOnOpen,
+    transitionDuration,
   };
 }
 

packages/components/accordion/stories/accordion.stories.tsx

@@ -377,6 +377,57 @@ const WithFormTemplate = (args: AccordionProps) => {
   );
 };
 
+const WithScrollOnOpenTemplate = (args: AccordionProps) => (
+  <div className="h-96 overflow-auto p-4 border rounded">
+    <h3 className="text-xl font-bold mb-6">Scroll container</h3>
+    <div className="mb-96">
+      <p className="mb-6">Scroll down to see the accordion</p>
+    </div>
+    <Accordion {...args} scrollOnOpen>
+      <AccordionItem key="1" aria-label="Accordion 1" title="Scroll on open (try opening this)">
+        <div className="p-4">
+          <p className="mb-4">{defaultContent}</p>
+          <Button color="primary">This will be scrolled into view</Button>
+        </div>
+      </AccordionItem>
+      <AccordionItem key="2" aria-label="Accordion 2" title="Accordion 2">
+        {defaultContent}
+      </AccordionItem>
+      <AccordionItem key="3" aria-label="Accordion 3" title="Accordion 3">
+        {defaultContent}
+      </AccordionItem>
+    </Accordion>
+  </div>
+);
+
+const WithCustomTransitionDurationTemplate = (args: AccordionProps) => (
+  <div className="flex flex-col gap-8">
+    <div>
+      <h3 className="mb-2 font-medium">Fast Transition (150ms)</h3>
+      <Accordion {...args} transitionDuration={150}>
+        <AccordionItem key="1" aria-label="Accordion 1" title="Fast transition accordion">
+          {defaultContent}
+        </AccordionItem>
+        <AccordionItem key="2" aria-label="Accordion 2" title="Accordion 2">
+          {defaultContent}
+        </AccordionItem>
+      </Accordion>
+    </div>
+
+    <div>
+      <h3 className="mb-2 font-medium">Slow Transition (800ms)</h3>
+      <Accordion {...args} transitionDuration={800}>
+        <AccordionItem key="1" aria-label="Accordion 1" title="Slow transition accordion">
+          {defaultContent}
+        </AccordionItem>
+        <AccordionItem key="2" aria-label="Accordion 2" title="Accordion 2">
+          {defaultContent}
+        </AccordionItem>
+      </Accordion>
+    </div>
+  </div>
+);
+
 export const Default = {
   render: Template,
 
@@ -529,3 +580,19 @@ export const CustomWithClassNames = {
     ...defaultProps,
   },
 };
+
+export const WithScrollOnOpen = {
+  render: WithScrollOnOpenTemplate,
+
+  args: {
+    ...defaultProps,
+  },
+};
+
+export const WithCustomTransitionDuration = {
+  render: WithCustomTransitionDurationTemplate,
+
+  args: {
+    ...defaultProps,
+  },
+};