Skip to main content

​
Overview

The setOptions() function allows you to modify React Scan configuration options dynamically at runtime. This is useful for toggling features or updating settings without reinitializing.

​
Signature

setOptions(userOptions: Partial<Options>): Options | undefined

​
Parameters

​
userOptions
Partial<Options>
required
Partial configuration object with options to update. Only the specified options will be changed; others remain unchanged.

​
Returns

​
options
Options | undefined
Returns the updated options object if successful, or undefined if an error occurred during validation.

​
Usage

​
Toggle Scanning

import { setOptions } from 'react-scan';

// Disable scanning
setOptions({ enabled: false });

// Re-enable scanning
setOptions({ enabled: true });

​
Update Multiple Options

import { setOptions } from 'react-scan';

setOptions({
  enabled: true,
  showToolbar: false,
  log: true,
  animationSpeed: 'slow',
});

​
Toggle Toolbar Visibility

import { setOptions } from 'react-scan';

function toggleToolbar() {
  const currentOptions = getOptions();
  setOptions({ 
    showToolbar: !currentOptions.value.showToolbar 
  });
}

​
Enable Production Mode

import { setOptions } from 'react-scan';

setOptions({
  dangerouslyForceRunInProduction: true,
});
Using dangerouslyForceRunInProduction in production environments can impact application performance.

​
Track Unnecessary Renders

import { setOptions } from 'react-scan';

setOptions({
  trackUnnecessaryRenders: true,
});
Tracking unnecessary renders can add meaningful overhead to React Scan. An unnecessary render is defined as a component re-rendering with no change to the component’s corresponding DOM subtree.

​
Validation

The function validates all provided options:
  • Boolean options must be valid booleans
  • animationSpeed must be one of: 'slow', 'fast', or 'off'
  • Callback options (onCommitStart, onRender, onCommitFinish) must be functions
  • Unknown options will trigger a console warning
  • Invalid options are ignored and not applied

​
Error Handling

import { setOptions } from 'react-scan';

// Invalid options will log warnings to console
setOptions({
  enabled: 'yes', // ❌ Invalid - must be boolean
  animationSpeed: 'medium', // ❌ Invalid - must be 'slow', 'fast', or 'off'
  unknownOption: true, // ❌ Invalid - unknown option
});

​
Persistence

Options set via setOptions() are automatically persisted to localStorage (except for callback functions). They will be restored when React Scan initializes on subsequent page loads.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us