usePrimaryButton

Configure and handle the persistent primary button

Defined in @coinbase/onchainkit

Configures a persistent primary button that appears at the bottom of the Mini App frame. Perfect for global actions that should always be accessible.

Parameters

options · SetPrimaryButtonOptions · required

Configuration object for the primary button appearance and behavior.

Show SetPrimaryButtonOptions properties

text · string · required

The text to display on the primary button.

callback · () => void · required

Function to execute when the primary button is clicked.

components/GameComponent.tsx

import { usePrimaryButton } from '@coinbase/onchainkit/minikit';
import { useState } from 'react';

enum GameState {
  RUNNING = 'running',
  PAUSED = 'paused',
  STOPPED = 'stopped'
}

export default function GameComponent() {
  const [gameState, setGameState] = useState(GameState.STOPPED);

  // Configure primary button based on game state
  usePrimaryButton(
    { 
      text: gameState === GameState.RUNNING ? 'PAUSE GAME' : 'START GAME' 
    },
    () => {
      setGameState(
        gameState === GameState.RUNNING 
          ? GameState.PAUSED 
          : GameState.RUNNING
      );
    }
  );

  return (
    <div className="game-container">
      <h2>Game Status: {gameState}</h2>
      {/* Game content */}
    </div>
  );
}

Usage Patterns

Global State Management

The primary button is perfect for actions that affect the entire app:

components/GlobalStateExamples.tsx

// Game controls
usePrimaryButton(
  { text: isPlaying ? 'Pause' : 'Play' },
  toggleGameState
);

// Modal controls  
usePrimaryButton(
  { text: 'Close' },
  closeModal
);

Form Submission

Use for primary form actions:

components/FormSubmit.tsx

usePrimaryButton(
  { text: isValid ? 'Submit' : 'Complete Required Fields' },
  handleFormSubmission
);

Multi-Step Flows

Navigate through complex workflows:

components/MultiStepFlow.tsx

usePrimaryButton(
  { text: getStepButtonText(currentStep) },
  () => advanceToNextStep()
);

Best Practices

Button Text Guidelines

• Keep it action-oriented: “Start Game”, “Submit Order”, “Continue”
• Be specific: “Save Changes” vs generic “Submit”
• Indicate state: “Pause Game” when playing, “Resume Game” when paused
• Stay concise: Aim for 1-3 words when possible

Layout Considerations

• The primary button appears at the bottom of the frame
• Don’t duplicate actions: Avoid having the same action as an in-content button
• Consider mobile: Button is optimized for thumb accessibility
• Test across clients: Button appearance may vary between Farcaster clients

Performance Tips

• Memoize callbacks: Use useCallback for complex button handlers
• Avoid frequent changes: Don’t update button text on every render
• Batch state updates: Update button config and app state together

components/HandlePrimaryAction.tsx

import { useCallback } from 'react';

const handlePrimaryAction = useCallback(() => {
  // Expensive operation
  performComplexAction();
}, [dependencies]);

usePrimaryButton(
  { text: 'Process Data' },
  handlePrimaryAction
);

The primary button is persistent across your entire Mini App session. Only use usePrimaryButton once per component tree to avoid conflicts.

The primary button provides a native, accessible way to surface your most important action. It’s especially effective for games, forms, and multi-step workflows where users need consistent access to the next action.