Spotlight Overlay API Reference

Composable: useSpotlightOverlay

The useSpotlightOverlay composable provides all the functionality for managing spotlight overlays.

State Properties

Property	Type	Description
positionX	Number	X coordinate of the instruction bar position
positionY	Number	Y coordinate of the instruction bar position
previousPositionX	Number	Previous X coordinate for animation purposes
previousPositionY	Number	Previous Y coordinate for animation purposes
arrowPosition	String	Current arrow position (see Arrow Positions below)
previousArrowPosition	String	Previous arrow position for animation
showFloatingInstructionBar	Boolean	Whether the instruction bar is visible
barConfig	Object	Configuration object for the instruction bar
highlightX	Number	X coordinate of the highlight center
highlightY	Number	Y coordinate of the highlight center
highlightRadius	Number	Radius of the highlight area
clipPathX	Number	X coordinate of the clip path area
clipPathY	Number	Y coordinate of the clip path area
clipPathHeight	Number	Height of the clip path area
clipPathWidth	Number	Width of the clip path area
highlightedElements	Array	Array of currently highlighted elements
highlightAreaBorderStyles	Object	Border styles for the highlight area
isAnimating	Boolean	Whether the component is currently animating
animationDuration	Number	Duration of animations in milliseconds

Methods

setInstructionBarConfigByElementId(data)

Main method for configuring and showing the spotlight overlay.

Parameters:

• data (Object) - Configuration object

Data Object Properties:

Property	Type	Required	Description
elementId	String	Yes	ID of the element to highlight
arrowPosition	String	Yes	Position of the arrow (see Arrow Positions)
isVisible	Boolean	Yes	Whether to show the instruction bar
config	Object	No	Configuration for the instruction bar
elementToHighLightId	String	No	Alternative element ID to highlight (overrides elementId)
elementHighlightClassName	String	No	CSS class to add to highlighted element (default: 'tour-highlight')

Config Object Properties:

Property	Type	Description
title	String	Text to display in the instruction bar
button	Object	Button configuration
hideArrowIcon	Boolean	Whether to hide the arrow icon
allowInteractionWithOtherElements	Boolean	Allow interaction with other page elements
closeButtonCallBack	Function	Callback when close button is clicked
onBlur	Function	Callback when instruction bar loses focus

Button Object Properties:

Property	Type	Description
label	String	Text to display on the button
callback	Function	Function to call when button is clicked

Example:

setInstructionBarConfigByElementId({
  elementId: 'my-button',
  arrowPosition: 'top',
  isVisible: true,
  config: {
    title: 'Click this button to continue',
    button: {
      label: 'Got it',
      callback: () => console.log('Button clicked!')
    },
    hideArrowIcon: false,
    allowInteractionWithOtherElements: true,
    closeButtonCallBack: () => console.log('Closed'),
    onBlur: () => console.log('Lost focus')
  }
})

resetInstructionBarConfig()

Resets the spotlight overlay to its initial state, hiding the instruction bar and clearing all configurations.

Example:

resetInstructionBarConfig()

setInstructionBarConfig(data)

Low-level method for setting instruction bar configuration directly.

Parameters:

• data (Object) - Configuration object with position, clipPath, highlight, arrowPosition, isVisible, config, and elementId properties

highlightElement({ elementId, className })

Adds a CSS class to a specific element to highlight it.

Parameters:

• elementId (String) - ID of the element to highlight
• className (String) - CSS class to add to the element

setPosition(data)

Sets the position of the instruction bar.

Parameters:

• data (Object) - Object with positionX and positionY properties

setPositionWithAnimation(data)

Sets the position of the instruction bar with animation.

Parameters:

• data (Object) - Object with positionX and positionY properties

setHighlight(data)

Sets the highlight area properties.

Parameters:

• data (Object) - Object with highlightX, highlightY, and highlightRadius properties

setClipPath(data)

Sets the clip path area properties.

Parameters:

• data (Object) - Object with clipPathX, clipPathY, clipPathHeight, and clipPathWidth properties

addHighlightedElements({ elementId, className })

Adds an element to the list of highlighted elements.

Parameters:

• elementId (String) - ID of the element to add
• className (String) - CSS class to apply to the element

resetHighlightedElements()

Removes all highlighted elements and clears the highlighted elements array.

Arrow Positions

The component supports the following arrow positions:

Position	Description
top	Arrow pointing down from above, centered
topLeft	Arrow pointing down from above, positioned left
topRight	Arrow pointing down from above, positioned right
topExtremeLeft	Arrow pointing down from above, extreme left position
topExtremeRight	Arrow pointing down from above, extreme right position
bottom	Arrow pointing up from below, centered
bottomLeft	Arrow pointing up from below, positioned left
bottomRight	Arrow pointing up from below, positioned right
bottomExtremeLeft	Arrow pointing up from below, extreme left position
bottomExtremeRight	Arrow pointing up from below, extreme right position
left	Arrow pointing right from the left side
right	Arrow pointing left from the right side

Usage Examples

Basic Highlight

import { useSpotlightOverlay } from '@/composables/useSpotlightOverlay'

const { setInstructionBarConfigByElementId } = useSpotlightOverlay()

// Simple highlight with title
setInstructionBarConfigByElementId({
  elementId: 'welcome-button',
  arrowPosition: 'top',
  isVisible: true,
  config: {
    title: 'Welcome! Click here to get started.'
  }
})

With Action Button

setInstructionBarConfigByElementId({
  elementId: 'submit-form',
  arrowPosition: 'bottom',
  isVisible: true,
  config: {
    title: 'Ready to submit your form?',
    button: {
      label: 'Submit Now',
      callback: () => {
        document.getElementById('submit-form').click()
        console.log('Form submitted!')
      }
    }
  }
})

Advanced Configuration

setInstructionBarConfigByElementId({
  elementId: 'settings-panel',
  arrowPosition: 'right',
  isVisible: true,
  config: {
    title: 'Configure your settings here',
    button: {
      label: 'Open Settings',
      callback: () => {
        // Custom action
        openSettingsPanel()
      }
    },
    hideArrowIcon: false,
    allowInteractionWithOtherElements: true,
    closeButtonCallBack: () => {
      console.log('Settings spotlight closed')
    },
    onBlur: () => {
      console.log('Settings spotlight lost focus')
    }
  },
  elementHighlightClassName: 'custom-highlight'
})

Multi-step Tour

const tourSteps = [
  {
    elementId: 'step1-button',
    arrowPosition: 'top',
    title: 'Step 1: Click here to begin',
    button: { label: 'Next', callback: () => showNextStep(1) }
  },
  {
    elementId: 'step2-input',
    arrowPosition: 'bottom',
    title: 'Step 2: Fill in your information',
    button: { label: 'Next', callback: () => showNextStep(2) }
  },
  {
    elementId: 'step3-submit',
    arrowPosition: 'top',
    title: 'Step 3: Submit when ready',
    button: { label: 'Finish', callback: () => completeTour() }
  }
]

let currentStep = 0

const showNextStep = (stepIndex) => {
  if (stepIndex < tourSteps.length) {
    setInstructionBarConfigByElementId({
      ...tourSteps[stepIndex],
      isVisible: true
    })
  }
}

const completeTour = () => {
  resetInstructionBarConfig()
  console.log('Tour completed!')
}

CSS Classes

The component automatically adds CSS classes to highlighted elements:

• tour-highlight - Default class added to highlighted elements
• Custom classes can be specified via elementHighlightClassName parameter

Animation and Transitions

The component includes several built-in animations:

• Position Changes: Smooth transitions when moving between elements
• Clip Path Animation: Close-in effect when highlighting new areas
• Arrow Position Changes: Smooth transitions when arrow position changes
• Content Updates: Fade effects for content changes

Animation duration can be controlled via the animationDuration property (default: 300ms).