@opendatalabs/vana-react

@opendatalabs/vana-react

React hooks and components for integrating with the Vana Network.

Production-ready React components for Vana App builders

Drop in secure, type-safe data upload and social sharing instead of building custom iframe integrations, managing authentication, or writing boilerplate message protocols.

Solves:

• Cross-origin iframe communication (we handle postMessage + origin validation)
• Wallet authentication flows (pre-built, tested, Vana Network–compatible)
• Data schema validation and upload (error handling included)
• Social sharing with copy-to-clipboard (works everywhere)

Tightly integrated with Vana App infrastructure – components point to app.vana.com and handle all the plumbing.

npm install @opendatalabs/vana-react
# or
yarn add @opendatalabs/vana-react
# or
pnpm add @opendatalabs/vana-react

Components

VanaAppUploadWidget

An embeddable iframe widget that facilitates data upload operations for Vana Apps.

VanaAppUploadWidget Features

• Cross-origin secure message communication
• Wallet authentication support
• Data upload with schema validation
• Theme customization (CSS custom properties)
• Full-viewport overlay (resize postMessage ignored/deprecated)
• TypeScript support

VanaAppUploadWidget Usage

import { VanaAppUploadWidget } from "@opendatalabs/vana-react";

function App() {
  const handleResult = (result: any) => {
    console.log("Upload successful:", result);
  };

  const handleError = (error: string) => {
    console.error("Upload error:", error);
  };

  const handleAuth = (walletAddress: string) => {
    console.log("Authenticated:", walletAddress);
  };

  return (
    <VanaAppUploadWidget
      appId="your-app-id"
      onResult={handleResult}
      onError={handleError}
      onAuth={handleAuth}
      schemaId={123}
      prompt="Upload your data"
      operation="prompt_gemini_agent"
      operationParams={{ goal: "Analyze user data" }}
      theme={{ "--primary": "#007bff" }}
      isOpen={true}
      onClose={() => console.log("Widget closed")}
    />
  );
}

VanaAppUploadWidget Props

Prop	Type	Required	Default	Description
appId	string	Yes	-	Your Vana application ID
onResult	(data: AgentOperationResult) => void	Yes	-	Callback when data upload completes successfully
onError	(error: string) => void	Yes	-	Callback when an error occurs
onAuth	(walletAddress: string) => void	Yes	-	Callback when wallet authentication succeeds
isOpen	boolean	No	true	Controls visibility; iframe stays mounted for prefetching (fullscreen)
onClose	() => void	No	-	Fires when child posts uploader:closed
onReady	() => void	No	-	Fires after child ready and config sent; safe for animation timing
iframeOrigin	string	No	https://app.vana.com	Origin URL for the iframe
schemaId	number	No	-	Schema ID for data validation
prompt	string	No	-	LLM inference prompt (legacy; prefer operation + operationParams)
operation	string	No	-	Agent operation (e.g. prompt_gemini_agent, llm_inference)
operationParams	Record<string, unknown>	No	-	Params forwarded to personal server with the operation
filters	Record<string, string>	No	-	JSONPath filters per schema for data pre-filtering
theme	VanaAppUploadTheme	No	-	CSS custom properties (e.g. { "--primary": "#6366f1" })
zIndex	number	No	1000	Z-index for stacking control

Ref API

The VanaAppUploadWidget component supports React forwardRef to expose the underlying iframe element:

const iframeRef = useRef<HTMLIFrameElement>(null);

<VanaAppUploadWidget
  ref={iframeRef}
  appId="your-app-id"
  {...otherProps}
/>

// Access iframe programmatically
iframeRef.current?.contentWindow?.postMessage(...);

Security Considerations

Origin Validation: The widget validates the iframe's origin on the first ready message before posting configuration. This protects against:

• Proxy/redirect chains that change the iframe's origin unexpectedly
• CSRF-style attacks via compromised iframe sources
• Message forwarding attacks (relay messages are filtered to "session"-only payloads)

Always use https://app.vana.com (or your authenticated domain) as the iframeOrigin prop. If you need to redirect or proxy the iframe, ensure the final destination origin matches your security policy.

Deprecated Props

• className: No longer used; widget layout is fully controlled internally for fullscreen experience. Accepted for backward compatibility but has no effect.
• resize postMessage: Ignored; widget is full-viewport by design. Height adjustment via postMessage is no longer supported.

VanaAppSocialShareWidget

A customizable social sharing component designed for Vana Data Apps. Provides seamless sharing to social platforms with copy-to-clipboard functionality and countdown notifications.

VanaAppSocialShareWidget Features

• One-click sharing to Twitter, Facebook, LinkedIn, and Instagram
• Copy-to-clipboard with automatic countdown timer
• Theme customization with icon sizing
• Flexible text generation with emojis and funny notes
• Toast notifications with progress indicator
• TypeScript support with full type definitions
• Zero external UI dependencies

VanaAppSocialShareWidget Usage

import { VanaAppSocialShareWidget } from "@opendatalabs/vana-react";

function MyDataApp() {
  const handleShare = (platform: string) => {
    console.log(`User shared on ${platform}`);
  };
  return (
    <VanaAppSocialShareWidget
      appName="Ice Cream Flavor"
      shareContent="ChocoVision Leader (Dark Chocolate)"
      shareEmoji="🍦"
      funnyNote="Apparently I'm in the same league as Beyoncé!"
      title="Share your flavor"
      onShare={handleShare}
      classNames={{
        root: "text-center",
        button: "w-12 h-12 rounded-full bg-white shadow-md hover:scale-105",
      }}
      theme={{ iconSize: 20 }}
    />
  );
}

VanaAppSocialShareWidget Props

Prop	Type	Required	Default	Description
appName	string	Yes	-	Name of your Vana app (e.g., "Ice Cream Flavor")
shareContent	string	Yes	-	Main content to share (e.g., user's result)
shareEmoji	string	No	-	Emoji to prepend to share content
funnyNote	string	No	-	Engaging note to add after content
title	string	No	"Share"	Title displayed above share buttons
callToAction	string	No	"Try @ app.vana.com"	CTA text in share message
hashtag	string	No	"#DATAREVOLUTION"	Hashtag to append to message
theme	VanaAppSocialShareTheme	No	{}	Theme configuration (iconSize)
onShare	(platform: SocialPlatform) => void	No	-	Callback when user shares
onShowToast	(message: ToastMessage) => void	No	-	Custom toast handler (uses internal if not set)
classNames	VanaAppSocialShareClassNames	No	{}	Class names for all component parts
hideTitle	boolean	No	false	Hide the title section
renderButton	(platform, Icon) => ReactNode	No	-	Custom render function for buttons
buttonComponent	React.ComponentType<ShareButtonProps>	No	-	Custom button component

ClassNames Options

Property	Type	Description
root	string	Root container class
title	string	Title section class (includes icon and text)
buttons	string	Buttons container class
button	string	Base class for all buttons
toast	string	Toast container class (if using internal toast)
toastContent	string	Toast content wrapper class
progress	string	Progress bar class for countdown

Run development build with watch mode

npm run dev

Run tests

npm test

Build for production

npm run build

Run linting

npm run lint

Type checking

npm run typecheck

Testing

License

MIT © OpenDataLabs