Skip to content

useFrame

Props

connectedAddress

  • Type: 0x${string} | undefined

The connected wallet address of the user. The address is part of the frame action payload when a frame button with action="tx" is pressed.

If the user presses transaction button without a connected wallet, the onConnectWallet function is called.

dangerousSkipSigning

  • Type: boolean

If true, the frame will not be signed before being sent to the frameActionProxy. This is useful for frames that don't verify signatures.

fetchFn

  • Type: typeof fetch

The custom fetch function to use instead of native fetch.

frameActionProxy

  • Type: string

The route used to POST frame actions. The post_url will be added as a the url query parameter.

frameGetProxy

  • Type: string

The route used to GET the initial frame via proxy.

signerState

  • Type: SignerStateInstance<T, B>

An signer state object used to determine what actions are possible.

homeframeUrl

  • Type: string | null

The url of the homeframe, if null won't load a frame.

frame

  • Type: Frame

The initial frame. if not specified will fetch it from the url prop.

onConnectWallet

  • Type: () => void

A function to start wallet connecting process. This function is called when a user presses a transaction button without a connected wallet.

onError

  • Type: (e: Error) => void

A function that can be used to customize how errors are reported to a user, by default it logs errors using console.error().

onLinkButtonClick

  • Type: (button: FrameButtonLink) => void

A function to handle link button presses by default it opens the link in new tab using window.open() if browser environment, otherwise it just logs the link.

onMint

  • Type: (t: onMintArgs) => void

A function to handle mint buttons.

onRedirect

  • Type: (url: string) => void

A function to handle redirect responses from the frame. This happens when you click a post_redirect button. By default it opens the link in new tab using window.open() if browser environment, otherwise it just logs the link.

onTransaction

  • Type: OnTransactionFunc

A function to handle transaction button presses, returns the transaction hash or null. The function is called when a user presses a transaction button and endpoint specified by target returns transaction data.

transactionDataSuffix

  • Type: 0x${string}

A suffix to add to the transaction data. Useful for client attribution in farcaster. Use the attribution helper from @frames.js/render/farcaster to generate this.

frameContext

  • Type: FrameContext

The context of this frame, used for generating Frame Action payloads.

extraButtonRequestPayload

  • Type: Record<string, unknown>

Extra data appended to the frame action payload.

Returns

  • Type: FrameState

fetchFrame

  • Type: (request: FrameRequest) => void

Fetches a frame from the frameGetProxy.

clearFrameStack

  • Type: () => void

Clears the frame stack.

frame

  • Type: Frame | null

The frame at the top of the stack (at index 0).

framesStack

  • Type: FramesStack

A stack of frames with additional context, with the most recent frame at index 0.

isLoading

  • Type: null | FrameStackPending

Whether the frame is loading.

inputText

  • Type: string

The input text.

setInputText

  • Type: (s: string) => void

Sets the input text.

onButtonPress

  • Type: (frame: Frame, frameButton: FrameButton, index: number) => void

Handles a button press on given Frame.

frameValidationErrors

  • Type: Record<string, string[]> | undefined | null

The frame validation errors.

error

  • Type: null | unknown

Whether there was an error loading the frame.

homeframeUrl

  • Type: string | null

The url of the frame.

Usage

frames.js/render/types.tsx
"use client";
import { FrameUI, fallbackFrameContext, FrameContext } from "@frames.js/render";
import { FrameImageNext } from "@frames.js/render/next";
import { FrameButton } from "frames.js";
import { useFrame } from "@frames.js/render/use-frame";
import {
  mockFarcasterSigner,
  createFrameActionMessageWithSignerKey,
} from "@frames.js/render/farcaster";
 
export default function Page() {
  const frameState = useFrame({
    // replace with your frame url
    homeframeUrl:
      "https://framesjs.org",
    // corresponds to the name of the route for POST in step 3
    frameActionProxy: "/frames",
    // corresponds to the name of the route for GET in step 3
    frameGetProxy: "/frames",
    frameContext: fallbackFrameContext,
    // map to your identity if you have one
    signerState: {
      // TODO: replace with your signer
      signer: mockFarcasterSigner,
      hasSigner: true,
      onSignerlessFramePress: () => {
        // Implement me
        alert("A frame button was pressed without a signer.");
      },
      signFrameAction: () => {
        alert("implement me.");
      },
    },
  });
 
  return (
    <FrameUI frameState={frameState} theme={{}} FrameImage={FrameImageNext} />
  );
}

Full example