Skip to main content

Ref Methods

SectionFlow exposes several methods via ref for programmatic control.

Usage​

import { useRef } from 'react';
import { SectionFlow } from 'sectionflow';
import type { SectionFlowRef } from 'sectionflow';

function MyComponent() {
  const ref = useRef<SectionFlowRef>(null);

  const scrollToTop = () => {
    ref.current?.scrollToOffset({ offset: 0, animated: true });
  };

  return (
    <>
      <Button onPress={scrollToTop} title="Scroll to Top" />
      <SectionFlow
        ref={ref}
        sections={sections}
        renderItem={renderItem}
      />
    </>
  );
}

Scroll Methods​

scrollToSection​

scrollToSection(sectionKey: string, animated?: boolean): void

Scrolls to the beginning of a section.

// Scroll to section with animation
ref.current?.scrollToSection('in-progress', true);

// Scroll without animation
ref.current?.scrollToSection('completed', false);

scrollToItem​

scrollToItem(params: {
  sectionKey: string;
  itemIndex: number;
  animated?: boolean;
  viewPosition?: number;
}): void

Scrolls to a specific item within a section.

ref.current?.scrollToItem({
  sectionKey: 'tasks',
  itemIndex: 5,
  animated: true,
  viewPosition: 0.5, // Center the item
});
ParameterTypeDescription
sectionKeystringKey of the section containing the item
itemIndexnumberIndex of the item within the section
animatedbooleanAnimate the scroll. Default: true
viewPositionnumberPosition in viewport (0-1). 0 = top, 0.5 = center, 1 = bottom

scrollToOffset​

scrollToOffset(params: {
  offset: number;
  animated?: boolean;
}): void

Scrolls to a specific offset.

// Scroll to top
ref.current?.scrollToOffset({ offset: 0, animated: true });

// Scroll to 500px from top
ref.current?.scrollToOffset({ offset: 500, animated: true });

scrollToEnd​

scrollToEnd(params?: { animated?: boolean }): void

Scrolls to the end of the list.

ref.current?.scrollToEnd({ animated: true });

Section Control Methods​

toggleSection​

toggleSection(sectionKey: string): void

Toggles the collapsed state of a section. Requires collapsible={true}.

// Toggle the 'archived' section
ref.current?.toggleSection('archived');

expandSection​

expandSection(sectionKey: string): void

Expands a collapsed section.

ref.current?.expandSection('tasks');

collapseSection​

collapseSection(sectionKey: string): void

Collapses an expanded section.

ref.current?.collapseSection('completed');

expandAllSections​

expandAllSections(): void

Expands all sections.

ref.current?.expandAllSections();

collapseAllSections​

collapseAllSections(): void

Collapses all sections.

ref.current?.collapseAllSections();

isSectionCollapsed​

isSectionCollapsed(sectionKey: string): boolean

Returns whether a section is currently collapsed.

const isCollapsed = ref.current?.isSectionCollapsed('archived');
console.log(isCollapsed); // true or false

Layout Methods​

getScrollOffset​

getScrollOffset(): number

Returns the current scroll offset.

const offset = ref.current?.getScrollOffset();
console.log(offset); // e.g., 250

getContentHeight​

getContentHeight(): number

Returns the total content height.

const height = ref.current?.getContentHeight();
console.log(height); // e.g., 5000

getVisibleItems​

getVisibleItems(): Array<{
  sectionKey: string;
  itemIndex: number;
  item: T;
}>

Returns currently visible items.

const visible = ref.current?.getVisibleItems();
console.log(visible);
// [
//   { sectionKey: 'tasks', itemIndex: 0, item: {...} },
//   { sectionKey: 'tasks', itemIndex: 1, item: {...} },
// ]

Example: Jump to Section Menu​

function SectionedList() {
  const ref = useRef<SectionFlowRef>(null);

  const jumpToSection = (key: string) => {
    ref.current?.scrollToSection(key, true);
  };

  return (
    <View style={{ flex: 1 }}>
      <View style={styles.quickNav}>
        {sections.map(section => (
          <TouchableOpacity
            key={section.key}
            onPress={() => jumpToSection(section.key)}
          >
            <Text>{section.title}</Text>
          </TouchableOpacity>
        ))}
      </View>
      <SectionFlow
        ref={ref}
        sections={sections}
        renderItem={renderItem}
        renderSectionHeader={renderSectionHeader}
        stickySectionHeadersEnabled
      />
    </View>
  );
}