# Social Sign In Buttons

Sign-in buttons for Google, Apple, GitHub and Microsoft, side by side or stacked.

- Category: Forms
- Page: https://wunderui.com/components/social-sign-in-buttons
- Tier: Free

## Install

```bash
npx wunderui-cli add social-sign-in-buttons
```

## Import

```tsx
import { SocialSignInButtons } from "@/components/blocks/auth"
```

## Minimal usage

Then use it:

```tsx
import { SocialSignInButtons } from "@wunderui/react"

export function SignInProviders() {
  return (
    <SocialSignInButtons
      providers={["google", "github"]}
      onSelect={(provider) => console.log("Sign in with", provider)}
    />
  )
}
```

Expected result: You see two white buttons side by side on a wide screen, Continue with Google and Continue with GitHub, each with its logo. Pressing one logs the provider.

## Usage

```tsx
import { SocialSignInButtons } from "@wunderui/react"

export function Example() {
  return (
    <SocialSignInButtons
      providers={["google", "github"]}
      onSelect={(provider) => console.log("Sign in with", provider)}
    />
  )
}
```

## When to use

### Use Social Sign In Buttons for

- A sign-in or sign-up card that offers an account at Google, Apple, GitHub or Microsoft
- A social-first screen where the providers come before the email form
- A row of providers on an invitation or onboarding page

### Use something else

- [Button](https://wunderui.com/components/button) for any action that is not the choice of a provider, such as Sign in with email
- [Divider with Label](https://wunderui.com/components/divider-with-label) for the or between the providers and an email form
- [Text Link Row](https://wunderui.com/components/text-link-row) for a line that leads to the other screen, such as Sign up

## Keyboard

The component handles no keys itself. Every provider is a native button and a tab stop, in the order you list them, with no arrow key navigation between them.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the next or the previous provider, and out of the group after the last one. A button inside a disabled fieldset is skipped. |
| `Enter` | Presses the focused button and calls `onSelect` with the provider. |
| `Space` | Presses the focused button, on release of the key, like any button. |

## Behavior

What the buttons do with their label and width, and what they leave to you.

- **Providers:** The providers list sets the buttons in the order you give it, Google and GitHub by default. Each provider can appear once, and an empty list renders an empty grid.
- **Layout and width:** Horizontal stacks below 640 px and sits in one row above, by window width, not container width. In a narrow container on a wide window use vertical or fewer providers.
- **Label:** The label is the prefix plus the provider name, like Continue with Google, or the name alone with an empty prefix. It stays on one line and runs out of a too-narrow column.
- **Press:** A press reports google, apple, github or microsoft. The component starts no sign-in, keeps no state and shows no pending or selected button, and it never submits a surrounding form.
- **States:** The buttons are plain Buttons: hover tints the fill, a press scales down a little, focus shows the ring. For a disabled state wrap them in a disabled fieldset, which dims them to 40 %.
- **Semantics:** The grid has no role or name, and each button is named by its label. To name the group wrap the buttons in a labelled group, and put a pending or failed status in an always-mounted status element.
- **Where it is used:** The split sign-in, centred sign-in, split sign-up, sign-up with password rules and social-first sign-up blocks use it.
- **Motion and reduced motion:** Fill and border change quickly, and a press scales the button to 97 %. With reduced motion the scale is off and only the colour changes.

## Anatomy

- `SocialSignInButtons`: A grid with a 12 px gap: horizontal is one column below 640 px window width and one row of equal columns above, vertical is always one column. It has no border, background or role.
- `Button`: One plain, rounded large Button per provider, as wide as its column. The label is the prefix plus the provider name on one line, or the name alone when the prefix is empty.
- `Mark`: The provider's 16 px logo before the label, hidden from screen readers. Google and Microsoft keep their brand colours, Apple and GitHub take the text colour.

## Best practices

### When to use

- Use it where a person picks an account at Google, Apple, GitHub or Microsoft on a sign-in or sign-up screen. The sign-in itself is yours, the component only reports the choice.

### Do

- Give each button room for its label: about 200 px with the prefix (two per row from 430 px) or 105 to 120 px without (four from 520 px). Otherwise go vertical.
- Put a Divider with Label saying or between the buttons and an email form, and use the same prefix on every button of a screen: Sign up with, Continue with or Sign in with.
- Show the wait and the failure next to the buttons. Wrap them in a disabled fieldset while a provider is pending, and write what happened, like Google sign-in was cancelled, not Something went wrong.
- Offer only providers that work on the screen, since a button that leads nowhere is worse than a missing one. Keep the order the same on every screen.

### Don't

- Don't put three or four providers with a prefix in one row. The label does not wrap or shorten, it runs out of the button over the next one.
- Don't draw your own marks or recolour the buttons. The marks follow each provider's brand guidelines, so use the component as it is.
- Don't use the buttons to show which accounts are already connected, because they have no selected, connected or loading state. For connections use a list of rows with a button each.

## API reference

### SocialSignInButtons

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string |  | Extra classes for the grid, for example `w-56` or `max-w-sm`. |
| layout | "horizontal" \| "vertical" | "horizontal" | `horizontal` is one row from 640 px of window width and a column below it, `vertical` is always a column. Default `horizontal`. |
| onSelect | (provider: SocialProvider) => void |  | Called with the provider when its button is pressed. Nothing else happens: start the sign-in here. |
| prefix | string | "Continue with" | The words before the provider name. An empty string leaves the name alone. Default `Continue with`. |
| providers | SocialProvider[] | ["google", "github"] | The buttons to show, in order: `google`, `apple`, `github` or `microsoft`. Default `google` and `github`. |

## Examples

### Providers: one to four

```tsx
import { SocialSignInButtons } from "@wunderui/react"

export function Example() {
  return (
    <SocialSignInButtons
      providers={["google"]}
      layout="vertical"
      onSelect={(provider) => console.log("Sign in with", provider)}
    />
  )
}
```

### Label: the prefix before the name

```tsx
import { SocialSignInButtons } from "@wunderui/react"

export function Example() {
  return (
    <SocialSignInButtons
      providers={["google", "github"]}
      layout="vertical"
      onSelect={(provider) => console.log("Sign in with", provider)}
    />
  )
}
```

### Layout: how many fit in a row

```tsx
import { SocialSignInButtons } from "@wunderui/react"

export function Example() {
  // A row needs about 200 px per button with the prefix. It stacks below 640 px of window width.
  return (
    <SocialSignInButtons
      providers={["google", "github"]}
      onSelect={(provider) => console.log("Sign in with", provider)}
    />
  )
}
```

### State: default, disabled, pending and error

```tsx
import { SocialSignInButtons } from "@wunderui/react"

export function Example() {
  return (
    <SocialSignInButtons
      providers={["google", "apple", "github"]}
      layout="vertical"
      onSelect={(provider) => console.log("Sign in with", provider)}
    />
  )
}
```

## In context

### Sign-in card: a provider that is pending, cancelled or unavailable

Pressing a provider starts a short wait with a spinner, the provider name and Cancel, while fields and buttons are off. The strip decides how the provider answers; no account is used.

```tsx
import { useEffect, useRef, useState } from "react"
import { AuthHeading, Button, DividerWithLabel, Input, SocialSignInButtons, Spinner, TextLinkRow } from "@wunderui/react"

type Provider = "google" | "apple" | "github" | "microsoft"
const NAMES: Record<Provider, string> = { google: "Google", apple: "Apple", github: "GitHub", microsoft: "Microsoft" }

// Your own sign-in call goes here. It resolves with the outcome of the provider.
async function signInWith(provider: Provider): Promise<"signed-in" | "cancelled" | "unavailable"> {
  await new Promise((resolve) => setTimeout(resolve, 1400))
  return "cancelled"
}

export function SignInCard() {
  const [pending, setPending] = useState<Provider | null>(null)
  const [result, setResult] = useState<{ tone: "error" | "success"; text: string } | null>(null)
  const run = useRef(0)
  useEffect(() => () => void (run.current += 1), [])

  async function start(provider: Provider) {
    const id = ++run.current
    setResult(null)
    setPending(provider)
    const outcome = await signInWith(provider)
    if (id !== run.current) return
    setPending(null)
    if (outcome === "signed-in") setResult({ tone: "success", text: `Signed in with ${NAMES[provider]}.` })
    else if (outcome === "cancelled") setResult({ tone: "error", text: `${NAMES[provider]} sign-in was cancelled. Try again or use your email address.` })
    else setResult({ tone: "error", text: `${NAMES[provider]} is not available right now. Try again in a minute or use another method.` })
  }

  return (
    <div className="flex w-full max-w-sm flex-col gap-6 rounded-xl border border-border bg-card p-6">
      <AuthHeading as="h2" title="Sign in to WunderUI" subtitle="Choose how you want to continue." />
      <fieldset disabled={pending !== null} aria-busy={pending !== null} className="m-0 min-w-0 border-0 p-0 flex flex-col gap-6">
        <SocialSignInButtons providers={["google", "apple", "github"]} layout="vertical" onSelect={start} />
        <DividerWithLabel>or</DividerWithLabel>
        <Input label="Email" type="email" placeholder="you@wunderui.com" />
        <Button type="submit" variant="gradient">
          Sign in with email
        </Button>
      </fieldset>
      <div className="flex min-h-9 items-center gap-2">
        {pending && <Spinner />}
        <span role={result?.tone === "error" ? "alert" : "status"} className={result?.tone === "error" ? "text-xs text-text-error" : "text-xs text-text-secondary"}>
          {pending ? `Waiting for ${NAMES[pending]}…` : result?.text}
        </span>
        {pending && (
          <Button size="sm" variant="plain" onClick={() => { run.current += 1; setPending(null) }}>
            Cancel
          </Button>
        )}
      </div>
      <TextLinkRow text="Don't have an account?" link="Sign up" href="/sign-up" className="justify-center" />
    </div>
  )
}
```

### Sign-up card: social first, with two or four providers

Stacked buttons with the prefix Sign up with, a divider and an email button. A press hands over to the provider: the card says it is redirecting, and Cancel brings the buttons back.

```tsx
import { useState } from "react"
import { AuthHeading, Button, DividerWithLabel, SocialSignInButtons, Spinner, TextLinkRow } from "@wunderui/react"

const NAMES = { google: "Google", apple: "Apple", github: "GitHub", microsoft: "Microsoft" }

export function SignUpCard() {
  const [pending, setPending] = useState<keyof typeof NAMES | null>(null)

  return (
    <div className="flex w-full max-w-sm flex-col gap-6 rounded-xl border border-border bg-card p-6">
      <AuthHeading as="h2" title="Create your workspace" subtitle="Start with an account you already have." />
      <fieldset disabled={pending !== null} aria-busy={pending !== null} className="m-0 min-w-0 border-0 p-0 flex flex-col gap-4">
        <SocialSignInButtons
          providers={["google", "apple", "github", "microsoft"]}
          layout="vertical"
          prefix="Sign up with"
          onSelect={(provider) => setPending(provider)}
        />
        <DividerWithLabel>or</DividerWithLabel>
        <Button variant="plain">Continue with email</Button>
      </fieldset>
      <div className="flex min-h-9 items-center gap-2">
        {pending && <Spinner />}
        <span role="status" className="text-xs text-text-secondary">
          {pending ? `Redirecting to ${NAMES[pending]}. Come back to finish.` : ""}
        </span>
        {pending && (
          <Button size="sm" variant="plain" onClick={() => setPending(null)}>
            Cancel
          </Button>
        )}
      </div>
      <TextLinkRow text="Already have an account?" link="Sign in" href="/sign-in" className="justify-center" />
    </div>
  )
}
```

## For AI agents

`get_component("social-sign-in-buttons")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
