react-es-ig-login

Well-typed React component for Instagram Business Login — the Instagram API with Instagram Login business login flow.

It is the Instagram counterpart to react-es-fb-login, but the underlying mechanics are different — see How it works.

• 💙 TypeScript first — fully typed props, params and responses
• 📦 Tiny, zero runtime dependencies
• 🔁 Full-page redirect or popup flow
• 🔒 Backend token exchange (the only safe way for Instagram)
• ⚛️ Works with React 16 → 20

Table of contents

• How it works
• Prerequisites
• Getting started
• Usage
  • Component
  • Popup flow
  • Custom render
  • InstagramLoginClient
• Scopes
• Props
• API reference
• Backend: exchanging the code
• TypeScript
• Examples
• Development
• Author
• License
• Links

How it works

⚠️ Important — read this before integrating.

Unlike Facebook Login, Instagram Business Login has no JavaScript SDK and there is no client-side access token. The flow is pure OAuth 2.0:

1. This component sends the user to https://www.instagram.com/oauth/authorize (redirect or popup).
2. Instagram redirects back to your redirectUri with a short-lived ?code=... (valid ~1 hour).
3. This component reads that code and hands it to your onSuccess callback.
4. Your backend exchanges the code for an access token by POSTing to https://api.instagram.com/oauth/access_token with the app's client_secret. The secret must never be exposed in browser code, so this step cannot happen in the package.

So: the frontend's only job is to obtain the code. Everything after that is the backend's responsibility.

 Browser (this package)                 Your Backend
 ──────────────────────                 ─────────────
 click "Login with Instagram"
        │
        ▼
 redirect to instagram.com/oauth/authorize
        │   (user approves)
        ▼
 redirect back to redirectUri?code=AUTH_CODE
        │
        ▼
 onSuccess({ code })  ───────POST code──────►  POST api.instagram.com/oauth/access_token
                                               (client_id, client_secret, code, redirect_uri)
                                                       │
                                                       ▼
                                               short-lived token ─► long-lived token (60d)

Prerequisites

1. A Meta app with the Instagram product added and Instagram Business Login set up.
2. Your Instagram App ID (used as appId / client_id).
3. One or more redirect URIs registered in the App Dashboard — the redirectUri you pass must match one of them exactly.
4. A backend endpoint that can exchange the authorization code for a token using your Instagram App Secret (see Backend: exchanging the code).

Getting started

npm i --save react-es-ig-login
# or
yarn add react-es-ig-login
# or
pnpm add react-es-ig-login

react is a peer dependency (^16 || ^17 || ^18 || ^19 || ^20).

Usage

Component

By default the component does a full-page redirect. Render the same component on your redirectUri page and it detects the redirect-back on mount (matching on state), then fires onSuccess / onFail automatically.

import InstagramLogin from 'react-es-ig-login';

<InstagramLogin
  appId="YOUR_INSTAGRAM_APP_ID"
  redirectUri="https://app.example.com/auth/instagram"
  scope="instagram_business_basic"
  onSuccess={(res) => {
    // Send res.code to your backend to exchange it for an access token.
    fetch('/api/instagram/exchange', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ code: res.code }),
    });
  }}
  onFail={(err) => {
    console.log('Login failed:', err);
  }}
/>;

Popup flow

Set useRedirect={false} to open the auth screen in a popup instead of navigating the whole page. The result is delivered via the callbacks without a page reload.

The redirectUri page must be same-origin with the page that opened the popup — the package polls popup.location to read the code once it returns. If your redirect page lives on a different origin, use the redirect flow.

<InstagramLogin
  appId="YOUR_INSTAGRAM_APP_ID"
  redirectUri="https://app.example.com/auth/instagram"
  useRedirect={false}
  popupParams={{ width: 500, height: 720 }}
  onSuccess={(res) => console.log(res.code)}
  onFail={(err) => console.log(err)}
/>

Custom render

Provide render to replace the default button with your own trigger:

<InstagramLogin
  appId="YOUR_INSTAGRAM_APP_ID"
  redirectUri="https://app.example.com/auth/instagram"
  render={({ onClick }) => (
    <button className="my-ig-button" onClick={onClick}>
      Continue with Instagram
    </button>
  )}
/>

Or pass children / style / className to style the built-in button.

InstagramLoginClient

Drive the flow manually without the component:

import { InstagramLoginClient } from 'react-es-ig-login';

// 1. Kick off login (full-page redirect)
InstagramLoginClient.redirect({
  client_id: 'YOUR_INSTAGRAM_APP_ID',
  redirect_uri: 'https://app.example.com/auth/instagram',
  scope: 'instagram_business_basic',
  state: 'instagramdirect',
});

// 2. On the redirect_uri page
if (InstagramLoginClient.isRedirected('instagramdirect')) {
  const res = InstagramLoginClient.getResponse();
  // res => { code, state } | { error, error_reason, error_description }
}

// Or just build the authorize URL yourself
const url = InstagramLoginClient.getAuthUrl({
  client_id: 'YOUR_INSTAGRAM_APP_ID',
  redirect_uri: 'https://app.example.com/auth/instagram',
});

Scopes

Pass a comma-separated string to scope:

| Scope | Purpose | | ------------------------------------ | ------------------------------- | | instagram_business_basic | Basic profile + media (default) | | instagram_business_content_publish | Publish content | | instagram_business_manage_messages | Read / manage messages | | instagram_business_manage_comments | Read / manage comments |

scope="instagram_business_basic,instagram_business_content_publish"

Props

| Property | Description | Type | Default | | ---------------- | ------------------------------------------------------------ | ----------------------------- | ----------------------------- | | appId * | Your Instagram App ID (client_id). | string | - | | redirectUri * | Registered redirect URI Instagram returns to. | string | - | | scope | Comma-separated permissions. | string | 'instagram_business_basic' | | state | CSRF value returned unchanged. | string | 'instagramdirect' | | enableFBLogin | Toggle "Continue with Facebook" on the auth screen. | boolean | true (Instagram default) | | forceReauth | Force the user to re-enter credentials. | boolean | false | | useRedirect | Full-page redirect (true) or popup (false). | boolean | true | | autoLoad | Start login on mount. | boolean | false | | onSuccess | Called with { code, state }. | function | - | | onFail | Called with { error, error_reason?, error_description? }. | function | - | | style | CSS for the default button. | CSSProperties | - | | className | Class for the default button. | string | - | | children | Button content. | ReactNode | 'Login with Instagram' | | render | Render a custom trigger: ({ onClick }) => ReactElement. | function | - | | authorizeParams| Override / extra authorize query params. | Partial<AuthorizeParams> | - | | popupParams | Popup sizing (used when useRedirect={false}). | { width?, height?, name? } | { width: 600, height: 700 } |

* = required.

API reference

InstagramLoginClient methods:

| Method | Returns | Description | | ----------------------------------------------- | ------------------------ | -------------------------------------------------------------------------- | | getAuthUrl(params) | string | Build the instagram.com/oauth/authorize URL. | | redirect(params) | void | Navigate the whole window to the authorize screen. | | openPopup(params, onSuccess, onFail, popup?) | void | Open the authorize screen in a popup and resolve via callbacks. | | isRedirected(state?) | boolean | Whether the current URL is a redirect-back (optionally matching state). | | parseResponse(search) | AuthResponse | Parse { code, state } or { error, ... } from a query string. | | getResponse() | AuthResponse | Parse the auth response from the current window URL. |

Where AuthResponse = SuccessResponse | FailResponse:

type SuccessResponse = { code: string; state?: string };

type FailResponse = {
  error: string; // 'access_denied' | 'popupBlocked' | 'popupClosed' | 'noWindow' | ...
  error_reason?: string;
  error_description?: string;
};

Backend: exchanging the code

The step this package deliberately leaves to your server:

POST https://api.instagram.com/oauth/access_token
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_INSTAGRAM_APP_ID
&client_secret=YOUR_INSTAGRAM_APP_SECRET
&grant_type=authorization_code
&redirect_uri=https://app.example.com/auth/instagram
&code=AUTH_CODE_FROM_onSuccess

The response contains a short-lived access token. Exchange it for a long-lived (60-day) token:

GET https://graph.instagram.com/access_token
  ?grant_type=ig_exchange_token
  &client_secret=YOUR_INSTAGRAM_APP_SECRET
  &access_token=SHORT_LIVED_TOKEN

Long-lived tokens can be refreshed (once they are ≥ 24h old and unexpired) at https://graph.instagram.com/refresh_access_token?grant_type=ig_refresh_token.

TypeScript

All public types are exported:

import type {
  InstagramLoginProps,
  AuthorizeParams,
  InstagramScope,
  SuccessResponse,
  FailResponse,
  AuthResponse,
  PopupParams,
} from 'react-es-ig-login';

Examples

See examples/ for component, popup, custom-render and client-only usage.

Development

npm install        # install dependencies
npm run check      # lint + type-check + tests (in parallel)
npm run check:test # jest only
npm run build      # emit dist/ with type declarations

Author

ankit5hukla — github.com/4nkit-5hukla

License

MIT

Links

• NPM
• GitHub
• (Official) Instagram Business Login Guide