Skip to main content

​
Options Interface

The Options interface allows you to customize React Scan’s behavior. Pass these options to the scan() function or configure them via build tool plugins. 
import { scan } from 'react-scan';

scan({
  enabled: process.env.NODE_ENV === 'development',
  showToolbar: true,
  log: false,
  // ... other options
});

​
Configuration Options

​
enabled
boolean
default:"true"
Enable or disable scanning.Recommended usage:
enabled: process.env.NODE_ENV === 'development'
This ensures React Scan only runs in development mode.
​
dangerouslyForceRunInProduction
boolean
default:"false"
Force React Scan to run in production.
Not recommended for production environments. This can add significant overhead to your application.
​
log
boolean
default:"false"
Log renders to the console.
This can add significant overhead when the app re-renders frequently.
Example output:
[React Scan] MyComponent rendered (23.4ms)
​
showToolbar
boolean
default:"true"
Show or hide the toolbar.If you set this to true and set enabled to false, the toolbar will still show, but scanning will be disabled.The toolbar provides:
  • Real-time FPS monitoring
  • Render count notifications
  • Inspector controls
​
animationSpeed
'slow' | 'fast' | 'off'
default:"'fast'"
Control the animation speed of render highlights.
  • 'fast' - Quick flash animations (recommended)
  • 'slow' - Slower, more visible animations
  • 'off' - No animations
​
trackUnnecessaryRenders
boolean
default:"false"
Track unnecessary renders and mark their outlines gray when detected.An unnecessary render is defined as a component re-rendering with no change to its corresponding DOM subtree.
Tracking unnecessary renders can add meaningful overhead to React Scan. Use this option sparingly during performance debugging sessions.
​
showFPS
boolean
default:"true"
Show the FPS meter in the toolbar.Displays real-time frames per second to help identify performance bottlenecks.
​
showNotificationCount
boolean
default:"true"
Show the number of slowdown notifications in the toolbar.Helps track how many performance issues have been detected during your session.
​
allowInIframe
boolean
default:"false"
Allow React Scan to run inside iframes.By default, React Scan is disabled in iframe contexts to avoid interference with embedded content.
​
_debug
'verbose' | false
default:"false"
Enable verbose internal error logging.Useful when React Scan is not behaving as expected and you want to provide information to maintainers when submitting an issue.Example:
scan({ _debug: 'verbose' });

​
Lifecycle Hooks

​
onCommitStart
() => void
Callback fired when a React commit phase starts.
scan({
  onCommitStart: () => {
    console.log('Commit started');
  }
});
​
onRender
(fiber: Fiber, renders: Array<Render>) => void
Callback fired when a component renders.Provides access to the fiber node and render information.
scan({
  onRender: (fiber, renders) => {
    console.log('Component:', fiber.type.name);
    console.log('Renders:', renders);
  }
});
See Types for Fiber and Render type definitions.
​
onCommitFinish
() => void
Callback fired when a React commit phase finishes.
scan({
  onCommitFinish: () => {
    console.log('Commit finished');
  }
});

​
Example Configurations

​
Basic Development Setup

import { scan } from 'react-scan';

scan({
  enabled: process.env.NODE_ENV === 'development',
  showToolbar: true,
});

​
Performance Debugging

import { scan } from 'react-scan';

scan({
  enabled: true,
  log: true,
  trackUnnecessaryRenders: true,
  animationSpeed: 'slow',
  onRender: (fiber, renders) => {
    const renderTime = renders[0]?.time;
    if (renderTime && renderTime > 16) {
      console.warn(`Slow render detected: ${fiber.type.name} (${renderTime}ms)`);
    }
  },
});

​
Minimal UI

import { scan } from 'react-scan';

scan({
  enabled: true,
  showToolbar: false,
  showFPS: false,
  showNotificationCount: false,
  animationSpeed: 'off',
});

​
Local Storage

React Scan persists certain options to localStorage for convenience:
  • enabled
  • log
  • showToolbar
  • animationSpeed
  • showFPS
  • showNotificationCount
  • allowInIframe
  • trackUnnecessaryRenders
Lifecycle hooks (onCommitStart, onRender, onCommitFinish) are not persisted.

​
See Also

  • Types - Type definitions for Fiber, Render, and more
  • CLI - Command-line interface
  • Vite Plugin - Vite integration

Build docs developers (and LLMs) love

Get started for freeTalk to us