@neynar/react

Introduction

@neynar/react is the official Frontend SDK from Neynar. This SDK includes React components to build Farcaster clients.

You can also test the components out in our Storybook.

Installation

1. Install the @neynar/react package using npm or yarn.

   For yarn:

   yarn add @neynar/react

   For npm:

   npm install @neynar/react

2. Make sure that the following peer dependencies are installed.

   {
     "@pigment-css/react": "^0.0.30",
     "hls.js": "^1.5.20",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "swr": "^2.3.2"
   }

   or if you want to install them all at once:

   For yarn:

   yarn add react react-dom @pigment-css/react hls.js swr

   For npm:

   npm install react react-dom @pigment-css/react hls.js swr

3. Import the following CSS file in your project's root file (e.g., layout.tsx for a Next.js app).

   import "@neynar/react/dist/style.css";

Components

Note: If you are using <NeynarAuthButton /> or if you're using <NeynarCastCard /> with allowReactions enabled (using Neynar reactions), please set your authorized origin to your local (localhost:6006 for Storybook) and production environments at dev.neynar.com.

<NeynarAuthButton />

This component lets you embed a Sign In With Neynar button in your app, which you can use for read-only or read + write access to the user's Farcaster account.

Params:

• label? (string): The text to display on the button. Default: "Sign in with Neynar"
• icon? (ReactNode): The icon to display on the button. Default: Neynar logo
• variant? (SIWN_variant): The variant of the button. Default: "primary"
• modalStyle? (CSSProperties): The style of the modal. Default: {}
• modalButtonStyle? (CSSProperties): The style of the modal button. Default: {}

Usage:

import { NeynarAuthButton } from "@neynar/react";

<NeynarAuthButton primary={true} label="Sign In with Neynar" />;

<NeynarProfileCard />

This component displays a user's Farcaster profile information.

Params:

• fid (number): The FID of the user to display.
• viewerFid? (number): The FID of the viewer. Default: undefined.
• containerStyles? (CSSProperties): Custom styles for the profile card. Default: {}

Usage:

import { NeynarProfileCard } from "@neynar/react";

<NeynarProfileCard fid={1} viewerFid={1} />;

<NeynarUserDropdown />

This component is a dropdown to search for Farcaster users.

Params:

• value (string): The currently selected user value.
• onChange (function): Callback function called with the new value when the user selection changes.
• style? (CSSProperties): Custom styles for the dropdown. Default: undefined.
• placeholder? (string): Placeholder text to display in the dropdown. Default: undefined.
• disabled? (boolean): Boolean indicating whether the dropdown is disabled. Default: false.
• viewerFid? (number): The FID of the viewer. Default: undefined.
• customStyles? (object): Custom styles for various elements within the dropdown. Properties include:
  • dropdown? (CSSProperties): Styles for the dropdown container.
  • listItem? (CSSProperties): Styles for the individual list items.
  • avatar? (CSSProperties): Styles for the user's avatar.
  • userInfo? (CSSProperties): Styles for the user's information text.
• limit? (number | null): The number of users that can be selected, or null for no limit. Default: null.

Usage:

import { NeynarUserDropdown } from "@neynar/react";

<NeynarUserDropdown
  value="rish"
  onChange={(newValue) => console.log(newValue)}
  viewerFid={1}
  limit={5}
/>;

<NeynarCastCard />

This component displays a specific cast (post) on Farcaster.

Params:

• type ('url' | 'hash'): The type of identifier used for the cast.
• identifier (string): The identifier (either URL or hash) for the cast.
• viewerFid? (number): The FID of the viewer. Default: undefined.
• allowReactions? (boolean, default = false): Whether to allow reactions on the cast
• renderEmbeds(boolean, default = true): Whether to allow rendering of cast embeds
• renderFrames(boolean, default = false): Whether to allow rendering of cast mini apps (note: if you pass in true, you must also set a value for onFrameBtnPress)
• onLikeBtnPress(() => boolean) A handler to add functionality when the like button is pressed. A response of true indicates the like action is successful
• onRecastBtnPress(() => boolean) A handler to add functionality when the recast button is pressed. A response of true indicates the recast action is successful
• onCommentBtnPress(() => boolean) A handler to add functionality when the comment button is pressed. A response of true indicates the comment action is successful
• onFrameBtnPress?: ( btnIndex: number, localFrame: NeynarFrame, setLocalFrame: React.Dispatch<React.SetStateAction<NeynarFrame>>, inputValue?: string ) => Promise<NeynarFrame>;: A handler to add functionality when a mini app button is pressed.
• containerStyles? (CSSProperties): Custom styles for the cast card's container. Default: {}
• textStyles? (CSSProperties): Custom styles for the cast card's text. Default: {}

Usage:

import { NeynarCastCard } from "@neynar/react";

<NeynarCastCard
  type="url"
  identifier="https://farcaster.xyz/dylsteck.eth/0xda6b1699"
  viewerFid={1}
/>;

<NeynarFeedList />

This component displays a list of casts (posts) on Farcaster.

Params:

• feedType ('following' | 'filter'): The type of feed to display.
• filterType? ('fids' | 'parent_url' | 'channel_id' | 'embed_url' | 'global_trending'): The filter type to apply to the feed. Default: undefined.
• fid? (number): The FID to filter the feed by. Default: undefined.
• fids? (string): The FIDs to filter the feed by. Default: undefined.
• parentUrl? (string): The parent URL to filter the feed by. Default: undefined.
• channelId? (string): The channel ID to filter the feed by. Default: undefined.
• embedUrl? (string): The embed URL to filter the feed by. Default: undefined.
• withRecasts? (boolean): Whether to include recasts in the feed. Default: true.
• limit? (number): The number of casts to display. Default: undefined.
• viewerFid? (number): The FID of the viewer. Default: undefined.
• clientId? (string): The client ID for the Neynar API. Default: undefined.

Usage:

import { NeynarFeedList } from "@neynar/react";

<NeynarFeedList feedType="filter" filterType="fids" fids="2" viewerFid={2} />;

<NeynarConversationList />

This component displays a conversation (thread) of casts (posts) on Farcaster.

Params:

• type ('url' | 'hash'): The type of identifier used for the conversation.
• identifier (string): The identifier (either URL or hash) for the conversation.
• replyDepth? (number): The depth of replies to include in the conversation. Default: 2.
• includeChronologicalParentCasts? (boolean): Whether to include chronological parent casts in the conversation. Default: false.
• limit? (number): The number of casts to display. Default: 20.
• viewerFid? (number): The FID of the viewer. Default: undefined.

Usage:

import { NeynarConversationList } from "@neynar/react";

<NeynarConversationList
  type="url"
  identifier="https://farcaster.xyz/dwr.eth/0x1b0792bc"
  replyDepth={2}
  limit={50}
  viewerFid={1}
/>;

<NeynarFrameCard />

This component displays a specific mini app on Farcaster.

Params:

• url (string): The URL to fetch the mini app data from.
• onFrameBtnPress: ( btnIndex: number, localFrame: NeynarFrame, setLocalFrame: React.Dispatch<React.SetStateAction<NeynarFrame>>, inputValue?: string ) => Promise<NeynarFrame>;: A handler to add functionality when a mini app button is pressed.
• initialFrame? (NeynarFrame): The initial mini app data to display. Default: undefined.

Usage:

import { NeynarFrameCard } from "@neynar/react";

<NeynarFrameCard url="https://events.xyz/events/a010d617" />;

Mini App Context

The mini app context provider is a wrapper around the @farcaster/miniapp-sdk package that provides additional Neynar-specific functionality. It handles mini app interactions, notification tracking, and analytics integration.

<MiniAppProvider />

This component provides the mini app context to its children. It should be placed at the root of your application or where mini app functionality is needed.

Params:

• analyticsEnabled (boolean, optional): Whether to enable analytics tracking. Default: false
• backButtonEnabled (boolean, optional): Whether to enable the back button functionality. Default: false
• returnUrl (string, optional): URL to navigate to when the back button is pressed and there's no navigation history. Default: undefined

Usage:

import { MiniAppProvider } from "@neynar/react";

function App() {
  return (
    <MiniAppProvider 
      analyticsEnabled={true}
      backButtonEnabled={true}
      returnUrl="https://example.com/return"
    >
      <YourApp />
    </MiniAppProvider>
  );
}

useMiniApp()

This hook provides access to the mini app context and its functionality. It extends the base Farcaster MiniApp SDK with Neynar-specific features like notification tracking and analytics.

Returns:

• isSDKLoaded (boolean): Whether the mini app SDK has been loaded
• context (MiniAppContext | undefined): The current mini app context
• openUrl (function): Function to open a URL in the mini app
• close (function): Function to close the mini app
• added (boolean): Whether the mini app has been added
• notificationDetails (MiniAppNotificationDetails | null): Details about mini app notifications
• lastEvent (string): The last mini app event that occurred
• addMiniApp (function): Function to add the mini app
• addMiniAppResult (string): Result of the last add mini app attempt

Usage:

import { useMiniApp } from "@neynar/react";

function YourComponent() {
  const { 
    isSDKLoaded, 
    context, 
    openUrl, 
    close, 
    added, 
    notificationDetails,
    lastEvent,
    addMiniApp,
    addMiniAppResult 
  } = useMiniApp();

  // Use the mini app context functionality
  return (
    <div>
      {isSDKLoaded && (
        <button onClick={() => addMiniApp()}>
          Add Mini App
        </button>
      )}
      {addMiniAppResult && <p>{addMiniAppResult}</p>}
    </div>
  );
}

How to securely implement write actions

There are currently two components that offer props for developers to handle write actions: NeynarCastCard(write action handlers for cast reactions) and NeynarFeedCard(write action handlers for mini app interactions). We highly recommend that you call Neynar's POST APIs(or other intended APIs) from your own, authenticated server to ensure that your Neynar API key credentials are not exposed on the client-side. Check out the example app below for a guide and example of securely implementing write actions.

Example app

Check out our example app for a demonstration of how to use @neynar/react.