RFC: Component-level Visibility-based Query Management

[minseong0324]

RFC: Component-level Visibility-based Query Management

🚀 Try It Out

The implementation is available at: Here

🎯 Problem Statement

TanStack Query's refetchOnWindowFocus works great for single-page applications, but it operates at the window level. In modern applications with complex layouts, we often need component-level control over when queries should be refreshed.

Real-world Scenarios

1. Tab/Panel Interfaces

// User switches between tabs - only active tab should refresh its data
function Dashboard() {
  const [activeTab, setActiveTab] = useState('analytics')
  
  return (
    <Tabs>
      <TabPanel id="analytics">
        {/* Should refresh when this tab becomes visible */}
        <AnalyticsPanel />
      </TabPanel>
      <TabPanel id="users">
        {/* Should NOT refresh when hidden */}
        <UsersPanel />
      </TabPanel>
    </Tabs>
  )
}

2. Dashboard Widgets

// Large dashboard with many widgets - refresh only visible ones
function WidgetDashboard() {
  return (
    <div style={{ height: '200vh' }}>
      <RevenueWidget />      {/* Visible */}
      <UsersWidget />        {/* Visible */}
      <OrdersWidget />       {/* Below viewport - shouldn't fetch until scrolled into view */}
      <InventoryWidget />    {/* Below viewport */}
    </div>
  )
}

3. Multi-QueryClient Environments (ex. MFE)

// Each section has its own QueryClient (e.g., micro-frontends, isolated components)
function App() {
  return (
    <>
      <QueryClientProvider client={userQueryClient}>
        <UserSection />  {/* Independent QueryClient */}
      </QueryClientProvider>
      <QueryClientProvider client={productQueryClient}>
        <ProductSection />  {/* Another independent QueryClient */}
      </QueryClientProvider>
    </>
  )
}

The Challenge

Current approaches have limitations:

// ❌ Window-level focus doesn't help with component visibility
refetchOnWindowFocus: true  // Refetches ALL queries when window focuses

// ❌ Manual scroll listeners are cumbersome
useEffect(() => {
  const observer = new IntersectionObserver(/* complex setup */)
  // ... lots of boilerplate
}, [])

// ❌ Hard to coordinate across multiple QueryClients
queryClient.invalidateQueries()  // Only affects its own QueryClient

💡 Proposed Solution: Component Focus Management

A component-level focus management system that:

1. Tracks component visibility using IntersectionObserver
2. Automatically invalidates/refetches queries when components become visible
3. Works across multiple QueryClient instances
4. Respects browser visibility state (tab switching, window blur)

🔧 API Design

Hook API

import { useComponentFocus } from '@tanstack/react-query-component-focus'

function DashboardWidget() {
  const { ref, isFocused } = useComponentFocus({
    componentKey: 'revenue-widget',
    invalidateOnFocus: true,    // Invalidate queries when visible
    forceRefetch: true,          // Force refetch even if data is fresh
  })

  const { data } = useQuery({
    queryKey: ['revenue'],
    queryFn: fetchRevenue,
  })

  return (
    <div ref={ref}>
      {isFocused && <Badge>Live</Badge>}
      <RevenueChart data={data} />
    </div>
  )
}

Component API

import { ComponentFocus } from '@tanstack/react-query-component-focus'

function DashboardWidget() {
  return (
    <ComponentFocus 
      componentKey="revenue-widget"
      invalidateOnFocus
      onFocusChange={(focused) => console.log('Visibility:', focused)}
    >
      <RevenueChart />
    </ComponentFocus>
  )
}

// With render prop for more control
<ComponentFocus
  componentKey="widget"
  render={({ isFocused, focus, blur }) => (
    <div className={isFocused ? 'active' : 'inactive'}>
      <Widget />
    </div>
  )}
/>

Group Management

import { ComponentFocusGroup } from '@tanstack/react-query-component-focus'

// Manage multiple related components together
<ComponentFocusGroup
  groupKey="dashboard-widgets"
  componentKeys={['widget1', 'widget2', 'widget3']}
>
  {({ registerComponent, focusGroup, blurGroup, focusedComponentKeys }) => (
    <>
      <button onClick={focusGroup}>Refresh All</button>
      <span>Visible: {focusedComponentKeys.length}/3</span>
      
      <div ref={registerComponent('widget1')}><RevenueWidget /></div>
      <div ref={registerComponent('widget2')}><UsersWidget /></div>
      <div ref={registerComponent('widget3')}><OrdersWidget /></div>
    </>
  )}
</ComponentFocusGroup>

Additional Components

// Conditional focus management
<ConditionalFocus
  when={isUserLoggedIn}
  componentKey="protected-content"
  fallback={<LoginPrompt />}
>
  <ProtectedDashboard />
</ConditionalFocus>

// Auto-focus on mount
<AutoFocus componentKey="notification" autoFocusDelay={500}>
  <NotificationBanner />
</AutoFocus>

// Focus boundary for sections
<FocusBoundary boundaryKey="main-content">
  <Header />
  <Content />
  <Footer />
</FocusBoundary>

🏗️ How It Works

Architecture

┌─────────────────────────────────────────────────┐
│              Your Application                   │
├─────────────────────────────────────────────────┤
│                                                 │
│  ┌────────────────┐  ┌────────────────┐        │
│  │  Component A   │  │  Component B   │        │
│  │  ┌──────────┐  │  │  ┌──────────┐  │        │
│  │  │  Query   │  │  │  │  Query   │  │        │
│  │  │  Client  │  │  │  │  Client  │  │        │
│  │  └──────────┘  │  │  └──────────┘  │        │
│  │       ↓        │  │       ↓        │        │
│  │  Focus Hook    │  │  Focus Hook    │        │
│  └────────────────┘  └────────────────┘        │
│            ↑                ↑                  │
│            └────────────────┘                  │
│         ComponentFocusManager                  │
│      (IntersectionObserver-based)              │
└─────────────────────────────────────────────────┘

Key Features

1. Viewport-based Detection: Uses IntersectionObserver to detect when components enter/leave viewport
2. Global Awareness: Respects browser visibility state (tab switching, window blur)
3. Manual Control: Programmatic focus/blur methods for edge cases
4. Group Coordination: Manage related components together

📊 Use Cases

Scenario	Benefit
Tab/Panel interfaces	Refresh data only for active tab
Dashboard widgets	Update visible widgets, skip hidden ones
Lazy-loaded sections	Fetch data when sections scroll into view
Multi-QueryClient environments	Coordinate refreshes across independent clients
Infinite scroll layouts	Manage query lifecycle for visible items
Modal/Dialog content	Refresh content when modals open

🤔 Questions for the Community

1. Is this a common enough problem to warrant official support?
2. Should this be part of core TanStack Query or a separate package?
3. What other use cases could benefit from component-level query management?
4. Should we extend this pattern to other frameworks (Vue, Solid, Svelte)?

💭 Alternative Approaches Considered

1. Manual IntersectionObserver setup

   • ❌ Lots of boilerplate code
   • ❌ No built-in query integration

2. Custom hooks per component

   • ❌ Duplicated logic across components
   • ❌ Hard to coordinate groups

3. Window-level focus only

   • ❌ Too coarse-grained for complex layouts
   • ❌ Can't handle visibility within same window

🎯 Conclusion

Component-level visibility-based query management provides a clean solution for:

• Performance optimization: Only fetch data for visible components
• Better UX: Keep data fresh where users are looking
• Developer experience: Declarative API, minimal boilerplate
• Flexibility: Works with single or multiple QueryClient instances

I'd love to hear your thoughts on this approach and whether it addresses real problems you're facing in production.

---

Tags: #rfc #feature-request #performance #visibility #architecture