FeatureDiscovery

Beta

Spotlight onboarding overlay to introduce UI features.

Installation

npm install @xaui/native

Import

import { FeatureDiscovery } from '@xaui/native/feature-discovery'

Basic Usage

Minimal example showing the component with its default configuration.

import { FeatureDiscovery } from '@xaui/native/feature-discovery'

export function Example() {
  return <FeatureDiscovery />
}

Basic

Show a spotlight around a referenced element.

import { useRef, useState } from 'react'
import { Pressable, Text, View } from 'react-native'
import { FeatureDiscovery } from '@xaui/native/feature-discovery'

export function BasicFeatureDiscoveryExample() {
  const [visible, setVisible] = useState(true)
  const targetRef = useRef<View>(null)

  return (
    <View>
      <View ref={targetRef} collapsable={false}>
        <Pressable>
          <Text>Target Element</Text>
        </Pressable>
      </View>

      <FeatureDiscovery
        isVisible={visible}
        targetRef={targetRef}
        title="Tap here first"
        description="This button starts your workflow."
        actionText="Got it"
        onActionPress={() => setVisible(false)}
        onDismiss={() => setVisible(false)}
      />
    </View>
  )
}

Controlled Trigger

Open the overlay from a dedicated trigger button.

import { useRef, useState } from 'react'
import { View } from 'react-native'
import { Button } from '@xaui/native/button'
import { FeatureDiscovery } from '@xaui/native/feature-discovery'

export function TriggeredFeatureDiscoveryExample() {
  const [visible, setVisible] = useState(false)
  const targetRef = useRef<View>(null)

  return (
    <View>
      <Button onPress={() => setVisible(true)}>Show Walkthrough</Button>

      <View ref={targetRef} collapsable={false}>
        <Button themeColor="secondary">Sync Data</Button>
      </View>

      <FeatureDiscovery
        isVisible={visible}
        targetRef={targetRef}
        title="Sync your data"
        description="Use this action to refresh local state from the server."
        actionText="Next"
        onActionPress={() => setVisible(false)}
        onDismiss={() => setVisible(false)}
      />
    </View>
  )
}

Custom Highlight Content

Render custom highlight UI and styling over the target.

import { useRef, useState } from 'react'
import { Text, View } from 'react-native'
import { FeatureDiscovery } from '@xaui/native/feature-discovery'

export function CustomHighlightFeatureDiscoveryExample() {
  const [visible, setVisible] = useState(true)
  const targetRef = useRef<View>(null)

  return (
    <View>
      <View ref={targetRef} collapsable={false}>
        <Text>Notifications</Text>
      </View>

      <FeatureDiscovery
        isVisible={visible}
        targetRef={targetRef}
        title="Stay informed"
        description="Enable notifications so you never miss updates."
        themeColor="warning"
        spotlightPadding={18}
        circleScale={1.85}
        highlightContent={
          <View style={{ paddingHorizontal: 10, paddingVertical: 6, borderRadius: 999, backgroundColor: '#fff' }}>
            <Text>NEW</Text>
          </View>
        }
        customAppearance={{
          actionText: { textTransform: 'uppercase' },
          messageContainer: { maxWidth: 280 },
        }}
        actionText="Understood"
        onActionPress={() => setVisible(false)}
        onDismiss={() => setVisible(false)}
      />
    </View>
  )
}