@flowsta/login-button

Login with Flowsta button components for React, Vue, Qwik, and vanilla JavaScript.

Easily integrate OAuth 2.0 authentication with Flowsta into your web application using pre-designed, production-ready button components.

Features

• ✅ 6 Button Variants - Dark, light, and neutral themes with pill or rectangle shapes
• ✅ Framework Support - React, Vue 3, Qwik, and vanilla JavaScript
• ✅ PKCE Built-in - Secure OAuth 2.0 with Proof Key for Code Exchange
• ✅ TypeScript - Full type definitions included
• ✅ Zero Dependencies - No external runtime dependencies
• ✅ Production Ready - Professional button designs with proper accessibility
• ✅ Resumable - Qwik support for instant-on apps

Installation

npm install @flowsta/login-button

Quick Start

React

import { FlowstaLoginButton } from '@flowsta/login-button/react';

function App() {
  return (
    <FlowstaLoginButton
      clientId="your-client-id"
      redirectUri="https://yourapp.com/callback"
      scopes={['openid', 'display_name', 'profile_picture']}
      variant="dark-pill"
      onSuccess={(data) => {
        console.log('Authorization code:', data.code);
        // Exchange code for token on your backend
      }}
      onError={(error) => {
        console.error('Login error:', error);
      }}
    />
  );
}

Vue 3

<template>
  <FlowstaLoginButton
    clientId="your-client-id"
    redirectUri="https://yourapp.com/callback"
    :scopes="['openid', 'display_name', 'profile_picture']"
    variant="dark-pill"
    @success="handleSuccess"
    @error="handleError"
  />
</template>

<script setup>
import { FlowstaLoginButton } from '@flowsta/login-button/vue';

const handleSuccess = (data) => {
  console.log('Authorization code:', data.code);
  // Exchange code for token on your backend
};

const handleError = (error) => {
  console.error('Login error:', error);
};
</script>

Qwik

import { component$ } from '@builder.io/qwik';
import { FlowstaLoginButton } from '@flowsta/login-button/qwik';

export default component$(() => {
  return (
    <FlowstaLoginButton
      clientId="your-client-id"
      redirectUri="https://yourapp.com/callback"
      scopes={['openid', 'display_name', 'profile_picture']}
      variant="dark-pill"
      onSuccess$={(data) => {
        console.log('Authorization code:', data.code);
        // Exchange code for token on your backend
      }}
      onError$={(error) => {
        console.error('Login error:', error);
      }}
    />
  );
});

Vanilla JavaScript

import { initFlowstaLoginButton } from '@flowsta/login-button/vanilla';

initFlowstaLoginButton('#login-container', {
  clientId: 'your-client-id',
  redirectUri: 'https://yourapp.com/callback',
  scopes: ['openid', 'display_name', 'profile_picture'],
  variant: 'dark-pill',
  onSuccess: (data) => {
    console.log('Authorization code:', data.code);
    // Exchange code for token on your backend
  },
  onError: (error) => {
    console.error('Login error:', error);
  }
});

Button Variants

Choose from 6 professionally designed button variants:

| Variant | Description | Best For | |---------|-------------|----------| | dark-pill | Dark background, rounded corners | Light backgrounds, modern UI | | dark-rectangle | Dark background, square corners | Light backgrounds, professional UI | | light-pill | Light background, rounded corners | Dark backgrounds, modern UI | | light-rectangle | Light background, square corners | Dark backgrounds, professional UI | | neutral-pill | Gray background, rounded corners | Any background, subtle integration | | neutral-rectangle | Gray background, square corners | Any background, professional look |

OAuth Flow

The button handles the OAuth 2.0 Authorization Code Flow with PKCE:

1. User clicks button → Component generates PKCE pair and redirects to Flowsta
2. User authenticates → Flowsta login page (login.flowsta.com)
3. User grants permissions → Consent screen shows requested scopes
4. Redirect back → Your app receives authorization code
5. Exchange code → Your backend exchanges code for access token

Handling the Callback

On your redirect URI page, handle the OAuth callback:

import { handleCallback, retrieveCodeVerifier, validateState } from '@flowsta/login-button';

// Parse callback parameters
const { code, state, error, errorDescription } = handleCallback();

if (error) {
  console.error('OAuth error:', error, errorDescription);
} else if (code && state) {
  // Validate state to prevent CSRF
  if (validateState(state)) {
    // Retrieve code verifier for token exchange
    const codeVerifier = retrieveCodeVerifier(state);
    
    // Exchange code for token on your backend
    const response = await fetch('/api/auth/token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ code, codeVerifier })
    });
    
    const { access_token } = await response.json();
    // Store token and create user session
  }
}

Backend Token Exchange

Exchange the authorization code for an access token:

// Example: Node.js backend
app.post('/api/auth/token', async (req, res) => {
  const { code, codeVerifier } = req.body;
  
  const response = await fetch('https://auth-api.flowsta.com/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      grant_type: 'authorization_code',
      code,
      client_id: process.env.FLOWSTA_CLIENT_ID,
      // No client_secret — PKCE (code_verifier) protects the exchange
      redirect_uri: process.env.REDIRECT_URI,
      code_verifier: codeVerifier
    })
  });
  
  const tokens = await response.json();
  res.json(tokens);
});

API Reference

Props / Options

All components accept the following configuration:

| Property | Type | Required | Default | Description | |----------|------|----------|---------|-------------| | clientId | string | ✅ | - | Your Flowsta application client ID | | redirectUri | string | ✅ | - | URI to redirect back to after authentication | | scopes | string[] | ❌ | ['openid', 'email', 'display_name'] | OAuth scopes: 'openid', 'email', 'display_name', 'username', 'did', 'profile_picture', 'holochain'. Note: email is absent for device-hosted accounts (the norm) — ask the user if you need one. | | variant | string | ❌ | 'dark-pill' | Button variant (see variants above) | | loginUrl | string | ❌ | 'https://login.flowsta.com' | Flowsta login URL | | className | string | ❌ | '' | Custom CSS class name | | disabled | boolean | ❌ | false | Whether button is disabled |

Events / Callbacks

React

interface FlowstaLoginButtonProps {
  onSuccess?: (data: { code: string; state: string }) => void;
  onError?: (error: { error: string; errorDescription?: string }) => void;
  onClick?: () => void;
}

Vue

<FlowstaLoginButton
  @success="(data) => { /* code, state */ }"
  @error="(error) => { /* error, errorDescription */ }"
  @click="() => { /* before redirect */ }"
/>

Qwik

<FlowstaLoginButton
  onSuccess$={(data) => { /* code, state */ }}
  onError$={(error) => { /* error, errorDescription */ }}
  onClick$={() => { /* before redirect */ }}
/>

Vanilla

{
  onSuccess: (data) => { /* code, state */ },
  onError: (error) => { /* error, errorDescription */ },
  onClick: () => { /* before redirect */ }
}

OAuth Scopes

profile (default)

Returns user's basic profile information:

{
  "userId": "user_abc123",
  "displayName": "John Doe",
  "did": "did:key:z6Mk...",
  "agentPubKey": "uhCAk..."
}

email

Returns user's email address (requires explicit permission):

{
  "userId": "user_abc123",
  "displayName": "John Doe",
  "did": "did:key:z6Mk...",
  "agentPubKey": "uhCAk...",
  "email": "[email protected]",
  "emailVerified": true
}

Note: Email is stored encrypted in Flowsta. Users must explicitly grant permission for your app to access it.

Utilities

The package also exports OAuth utilities for custom implementations:

import {
  generatePKCEPair,
  generateCodeChallenge,
  generateState,
  buildAuthorizationUrl,
  handleCallback,
  validateState
} from '@flowsta/login-button';

// Generate PKCE pair
const { verifier, challenge } = await generatePKCEPair();

// Build custom authorization URL
const { url, state, codeVerifier } = await buildAuthorizationUrl({
  clientId: 'your-client-id',
  redirectUri: 'https://yourapp.com/callback',
  scopes: ['openid', 'display_name', 'profile_picture']
});

// Handle callback
const { code, state, error } = handleCallback();

// Validate state
const isValid = validateState(state);

Examples

Custom Button Content

React

<FlowstaLoginButton
  clientId="your-client-id"
  redirectUri="https://yourapp.com/callback"
>
  <span>Custom Login Text</span>
</FlowstaLoginButton>

Vue

<FlowstaLoginButton
  clientId="your-client-id"
  redirectUri="https://yourapp.com/callback"
>
  <span>Custom Login Text</span>
</FlowstaLoginButton>

Vanilla with Custom Container

import { createFlowstaLoginButton } from '@flowsta/login-button/vanilla';

const button = createFlowstaLoginButton({
  clientId: 'your-client-id',
  redirectUri: 'https://yourapp.com/callback',
  variant: 'neutral-pill'
});

document.getElementById('my-container').appendChild(button);

TypeScript

Full TypeScript support with exported types:

import type {
  ButtonVariant,
  FlowstaScope,
  FlowstaLoginConfig,
  FlowstaLoginSuccess,
  FlowstaLoginError,
  FlowstaLoginButtonProps,
  FlowstaLoginButtonQwikProps,
  VueFlowstaLoginButtonProps
} from '@flowsta/login-button';

Browser Support

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)
• Modern browsers with ES2020+ and Web Crypto API support

Security

• PKCE: All OAuth flows use PKCE (Proof Key for Code Exchange) for enhanced security
• State Parameter: CSRF protection via state parameter validation
• Secure Storage: Code verifiers stored in sessionStorage with state correlation
• No Client Secret: Client secret never exposed to browser (backend only)

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT © Flowsta

Support

• 📖 Documentation
• 💬 Community
• 🐛 Issue Tracker
• 📧 Email Support

Related Packages

• @flowsta/auth - Core authentication SDK (token exchange, userinfo, Sign It, React bindings)
• @flowsta/holochain - Vault integration: sign-in, agent linking, encrypted backups

Made with ❤️ by the Flowsta team

Changelog

0.1.4 (2026-06-13)

• Fixed: button images broke in production builds. All framework variants previously resolved the button artwork via paths that only exist in dev environments. The official artwork is now inlined as optimized data URIs (~7 KB gzipped total) — works with every bundler, plain <script> tags, and SSR, with no CDN dependency.
• Button SVG assets optimized (69% smaller).

0.1.3

• Initial public release: React, Vue, Qwik, and vanilla JS components with PKCE and state handling.