Feat: ui.page_scroller

nicegui/page_layout.py

@@ -307,6 +307,44 @@ def __init__(self,
             self._props['expand'] = True
 
 
+class PageScroller(PageSticky):
+
+    def __init__(self,
+                 position: PageStickyPositions = 'bottom-right',
+                 x_offset: float = 0,
+                 y_offset: float = 0,
+                 *,
+                 expand: bool = False,
+                 scroll_offset: int = 1000,
+                 duration: int = 300,
+                 reverse: bool = False,
+                 ) -> None:
+        """Page scroller
+
+        This element is based on Quasar's `QPageScroller <https://quasar.dev/layout/page-scroller>`_ component.
+
+        It is very similar to ``ui.page_sticky``, sharing ``position``, ``x_offset``, and ``y_offset`` parameters.
+
+        However, ``ui.page_sticky`` is always visible, and ``ui.page_scroller`` only appears after the ``scroll-offset`` is reached.
+
+        Once visible, the user can click on it to quickly get back to the top of the page in ``duration`` ms.
+
+        :param position: position on the screen (default: "bottom-right")
+        :param x_offset: horizontal offset (default: 0)
+        :param y_offset: vertical offset (default: 0)
+        :param expand: whether to fully expand instead of shrinking to fit the content (default: ``False``)
+        :param scroll_offset: the vertical offset in pixels at which the scroller becomes visible (default: 1000)
+        :param duration: the duration in milliseconds for the scroll animation (default: 300)
+        :param reverse: if True, the scroller will work in reverse, showing when at the top of the page, and scrolls to bottom when triggered (default: ``False``)
+        """
+        super().__init__(position=position, x_offset=x_offset, y_offset=y_offset, expand=expand)
+        self.tag = 'q-page-scroller'
+        self._props['scroll-offset'] = scroll_offset
+        self._props['duration'] = duration
+        if reverse:
+            self._props['reverse'] = True
+
+
 def _check_current_slot(element: Element) -> None:
     parent = context.slot.parent
     if parent != parent.client.content:

nicegui/ui.py

@@ -75,6 +75,7 @@
     'number',
     'on',
     'page',
+    'page_scroller',
     'page_sticky',
     'page_title',
     'pagination',
@@ -244,6 +245,7 @@
 from .page_layout import Footer as footer
 from .page_layout import Header as header
 from .page_layout import LeftDrawer as left_drawer
+from .page_layout import PageScroller as page_scroller
 from .page_layout import PageSticky as page_sticky
 from .page_layout import RightDrawer as right_drawer
 from .ui_run import run

website/documentation/content/page_layout_documentation.py

@@ -5,12 +5,25 @@
 
 @doc.auto_execute
 @doc.demo('Page Layout', '''
-    With `ui.header`, `ui.footer`, `ui.left_drawer` and `ui.right_drawer` you can add additional layout elements to a page.
-    The `fixed` argument controls whether the element should scroll or stay fixed on the screen.
-    The `top_corner` and `bottom_corner` arguments indicate whether a drawer should expand to the top or bottom of the page.
-    See <https://quasar.dev/layout/header-and-footer> and <https://quasar.dev/layout/drawer> for more information about possible props.
-    With `ui.page_sticky` you can place an element "sticky" on the screen.
-    See <https://quasar.dev/layout/page-sticky> for more information.
+    With [`ui.header`](page_layout#reference_for_ui_header),
+    [`ui.footer`](page_layout#reference_for_ui_footer),
+    [`ui.left_drawer`](page_layout#reference_for_ui_left_drawer) and
+    [`ui.right_drawer`](page_layout#reference_for_ui_right_drawer) you can add additional layout elements to a page.
+
+    - The `fixed` argument controls whether the element should scroll or stay fixed on the screen.
+    - The `top_corner` and `bottom_corner` arguments indicate whether a drawer should expand to the top or bottom of the page.
+    - See <https://quasar.dev/layout/header-and-footer> and <https://quasar.dev/layout/drawer> for more information about possible props.
+
+    With [`ui.page_sticky`](page_layout#reference_for_ui_page_sticky) you can place an element "sticky" on the screen.
+
+    - The `position`, `x_offset` and `y_offset` arguments control the position of the sticky element.
+    - See <https://quasar.dev/layout/page-sticky> for more information.
+
+    With [`ui.page_scroller`](page_layout#reference_for_ui_page_scroller) you can add a scroll-to-top button to the page.
+
+    - Shares the basic arguments with [`ui.page_sticky`](page_layout#reference_for_ui_page_sticky).
+    - The `scroll_offset`, `duration` and `reverse` arguments control the behavior.
+    - See <https://quasar.dev/layout/page-scroller> for more information.
 ''')
 def page_layout_demo():
     @ui.page('/page_layout')
@@ -26,6 +39,10 @@ def page_layout():
             ui.label('RIGHT DRAWER')
         with ui.footer().style('background-color: #3874c8'):
             ui.label('FOOTER')
+        with ui.page_sticky(position='bottom-left', x_offset=20, y_offset=20):
+            ui.button('Sticky Button', on_click=lambda: ui.notify('Sticky Button Clicked'))
+        with ui.page_scroller(position='bottom-right', x_offset=20, y_offset=20):
+            ui.button('Scroll to Top')
 
     ui.link('show page with fancy layout', page_layout)
 
@@ -35,3 +52,4 @@ def page_layout():
 doc.reference(ui.right_drawer, title='Reference for ui.right_drawer')
 doc.reference(ui.footer, title='Reference for ui.footer')
 doc.reference(ui.page_sticky, title='Reference for ui.page_sticky')
+doc.reference(ui.page_scroller, title='Reference for ui.page_scroller')