Skip to content

Add SDK specificity across the docs for the Customizing Clerk section #2746

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 19 commits into
base: main
Choose a base branch
from
+2,270 −2,310
Open

Add SDK specificity across the docs for the Customizing Clerk section #2746

Show file tree
Hide file tree
Changes from 11 commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
3a69542
Remove all remix code examples
SarahSoutoul Oct 27, 2025
24d7ee0
Localization page#
SarahSoutoul Oct 27, 2025
c32abf2
Fix linting and build
SarahSoutoul Oct 27, 2025
392d0ec
Add changes to other guides
SarahSoutoul Oct 28, 2025
c87d697
Fix linting
SarahSoutoul Oct 28, 2025
5cc3cb8
Add descriptions for code examples
SarahSoutoul Oct 28, 2025
9c5985f
Fix highlighting
SarahSoutoul Oct 28, 2025
3c88cb9
Tackle themes page + clarification of text
SarahSoutoul Oct 28, 2025
7e8c8c7
Fix prettier stuff
SarahSoutoul Oct 28, 2025
63d4822
Fix issues when testing
SarahSoutoul Oct 28, 2025
fd126d1
Fix linting
SarahSoutoul Oct 28, 2025
96df89f
Restructure the code examples and wordign
SarahSoutoul Oct 29, 2025
a1f1718
Fix linting
SarahSoutoul Oct 29, 2025
929ab2f
Fix issue with themes page
SarahSoutoul Oct 29, 2025
583edfe
Fix highlighting + add more examples
SarahSoutoul Oct 29, 2025
87bf4de
Add Astro + JS
SarahSoutoul Nov 3, 2025
3f0c784
Add JS examples
SarahSoutoul Nov 12, 2025
07b8cea
Switch orders
SarahSoutoul Nov 12, 2025
303045c
Merge branch 'main' into ss/sdk-specificity-project-customizing-clerk
SarahSoutoul Nov 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
159 changes: 83 additions & 76 deletions docs/guides/customizing-clerk/appearance-prop/captcha.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,27 +36,29 @@ The `captcha` property can be used to change the appearance of the CAPTCHA widge

## Usage

<Tabs items={["Next.js", "Astro", "React", "Remix", "Nuxt", "Vue"]}>
<Tabs items={["SDKs using <ClerkProvider/>", "Astro", "JavaScript", "Vue", "Nuxt", "Fastify"]}>
<Tab>
```tsx {{ prettier: false, filename: 'app.tsx' }}
import { ClerkProvider } from '@clerk/nextjs';
For any SDK using `<ClerkProvider />`, pass the `captcha` property to the `appearance` prop of the [`<ClerkProvider>`](/docs/reference/components/clerk-provider) component.

```tsx {{ mark: [[3, 7]] }}
<ClerkProvider
appearance={{
captcha: {
theme: 'dark',
size: 'flexible',
language: 'es-ES',
}
},
}}
>
{/* ... */}
</ClerkProvider>;
</ClerkProvider>
```
</Tab>

<Tab>
```js {{ filename: 'astro.config.mjs' }}
In Astro, pass the `captcha` property to the `appearance` prop of the [`clerk()`](/docs/reference/astro/overview) integration.

```js {{ filename: 'astro.config.mjs', mark: [[7, 11]] }}
import clerk from '@clerk/astro'

export default defineConfig({
Expand All @@ -76,73 +78,74 @@ The `captcha` property can be used to change the appearance of the CAPTCHA widge
</Tab>

<Tab>
```tsx {{ filename: 'app.tsx', mark: [[13, 18]] }}
import React from 'react'
import './App.css'
import { ClerkProvider } from '@clerk/clerk-react'

if (!process.env.REACT_APP_CLERK_PUBLISHABLE_KEY) {
throw new Error('Missing Publishable Key')
}
const clerkPubKey = process.env.REACT_APP_CLERK_PUBLISHABLE_KEY

function App() {
return (
<ClerkProvider
appearance={{
captcha: {
theme: 'dark',
size: 'flexible',
language: 'es-ES',
},
}}
publishableKey={clerkPubKey}
>
{/* ... */}
</ClerkProvider>
)
}

export default App
```
</Tab>
In JavaScript, pass the `captcha` property to the `appearance` prop of the [`clerk.load()`](/docs/reference/javascript/clerk#load) method.

<Tab>
```tsx {{ filename: 'app/root.tsx', mark: [[35, 40]] }}
// Import ClerkApp
import { ClerkApp } from '@clerk/remix'
import type { MetaFunction, LoaderFunction } from '@remix-run/node'
Use the following tabs to view the code necessary for each file.

import { Links, LiveReload, Meta, Outlet, Scripts, ScrollRestoration } from '@remix-run/react'
<CodeBlockTabs options={["main.js", "index.html"]}>
```js {{ filename: 'main.js', mark: [[8, 12]], collapsible: true }}
import { Clerk } from '@clerk/clerk-js'

import { rootAuthLoader } from '@clerk/remix/ssr.server'
const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

export const meta: MetaFunction = () => ({
charset: 'utf-8',
title: 'New Remix App',
viewport: 'width=device-width,initial-scale=1',
})
const clerk = new Clerk(clerkPubKey)
await clerk.load({
appearance: {
captcha: {
theme: 'dark',
size: 'flexible',
language: 'es-ES',
},
},
})

if (clerk.isSignedIn) {
document.getElementById('app').innerHTML = `
<div id="user-button"></div>
`

const userButtonDiv = document.getElementById('user-button')

clerk.mountUserButton(userButtonDiv)
} else {
document.getElementById('app').innerHTML = `
<div id="sign-in"></div>
`

const signInDiv = document.getElementById('sign-in')

clerk.mountSignIn(signInDiv)
}
```

```html {{ filename: 'index.html' }}
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<link rel="icon" type="image/svg+xml" href="/vite.svg" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Clerk + JavaScript App</title>
</head>
<body>
<div id="app"></div>
<script type="module" src="main.js" async crossorigin="anonymous"></script>
</body>
</html>
```
</CodeBlockTabs>
</Tab>

export const loader: LoaderFunction = (args) => rootAuthLoader(args)

function App() {
return (
<html lang="en">
<head>
<Meta />
<Links />
</head>
<body>
<Outlet />
<ScrollRestoration />
<Scripts />
<LiveReload />
</body>
</html>
)
}

export default ClerkApp(App, {
<Tab>
In Vue, pass the `captcha` property to the `appearance` prop of the [`clerkPlugin()`](/docs/reference/vue/overview) integration.

```ts {{ filename: 'src/main.ts', mark: [[8, 12]] }}
import { createApp } from 'vue'
import App from './App.vue'
import { clerkPlugin } from '@clerk/vue'

const app = createApp(App)
app.use(clerkPlugin, {
appearance: {
captcha: {
theme: 'dark',
Expand All @@ -151,11 +154,14 @@ The `captcha` property can be used to change the appearance of the CAPTCHA widge
},
},
})
app.mount('#app')
```
</Tab>

<Tab>
```ts {{ filename: 'nuxt.config.ts' }}
In Nuxt, pass the `captcha` property to the `appearance` prop of the [`defineNuxtConfig()`](/docs/reference/nuxt/clerk-middleware) integration.

```ts {{ filename: 'nuxt.config.ts', mark: [[5, 9]] }}
export default defineNuxtConfig({
modules: ['@clerk/nuxt'],
clerk: {
Expand All @@ -172,13 +178,15 @@ The `captcha` property can be used to change the appearance of the CAPTCHA widge
</Tab>

<Tab>
```ts {{ filename: 'src/main.ts' }}
import { createApp } from 'vue'
import App from './App.vue'
import { clerkPlugin } from '@clerk/vue'
In Fastify, pass the `captcha` property to the `appearance` prop of the [`clerkPlugin()`](/docs/reference/fastify/clerk-plugin) integration.

const app = createApp(App)
app.use(clerkPlugin, {
```ts {{ filename: 'src/main.ts', mark: [[8, 12]] }}
import Fastify from 'fastify'
import { clerkPlugin } from '@clerk/fastify'

const fastify = Fastify({ logger: true })

fastify.register(clerkPlugin, {
appearance: {
captcha: {
theme: 'dark',
Expand All @@ -187,7 +195,6 @@ The `captcha` property can be used to change the appearance of the CAPTCHA widge
},
},
})
app.mount('#app')
```
</Tab>
</Tabs>
106 changes: 96 additions & 10 deletions docs/guides/customizing-clerk/appearance-prop/layout.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ description: Utilize Clerk's layout prop in order to change the layout of the <S

{/* JS file: https://github.com/clerk/javascript/blob/main/packages/types/src/appearance.ts#L538 */}

The `layout` property can be used to change the layout of the [`<SignIn/>`](/docs/reference/components/authentication/sign-in) and [`<SignUp/>`](/docs/reference/components/authentication/sign-up) components, as well as set important links to your support, terms, and privacy pages.
The `layout` property can be used to change the layout of the [`<SignIn/>`](/docs/reference/components/authentication/sign-in) and [`<SignUp/>`](/docs/reference/components/authentication/sign-up) components, as well as set important links to your support, terms, and privacy pages. It is passed as a parameter to the [`appearance` prop](/docs/guides/customizing-clerk/appearance-prop/overview).

## Properties

Expand Down Expand Up @@ -95,27 +95,29 @@ The `layout` property can be used to change the layout of the [`<SignIn/>`](/doc

## Usage

<Tabs items={["Next.js", "Astro", "Vue", "Nuxt"]}>
<Tabs items={["SDKs using <ClerkProvider/>", "Astro", "JavaScript", "Vue", "Nuxt", "Fastify"]}>
<Tab>
```tsx {{ prettier: false, filename: 'app.tsx' }}
import { ClerkProvider } from '@clerk/nextjs';
For any SDK using `<ClerkProvider />`, pass the `layout` property to the `appearance` prop of the [`<ClerkProvider>`](/docs/reference/components/clerk-provider) component.

```tsx {{ mark: [[3, 7]] }}
<ClerkProvider
appearance={{
layout: {
socialButtonsPlacement: 'bottom',
socialButtonsVariant: 'iconButton',
termsPageUrl: 'https://clerk.com/terms'
}
termsPageUrl: 'https://clerk.com/terms',
},
}}
>
{/* ... */}
</ClerkProvider>;
</ClerkProvider>
```
</Tab>

<Tab>
```js {{ filename: 'astro.config.mjs' }}
In Astro, pass the `layout` property to the `appearance` prop of the [`clerk()`](/docs/reference/astro/overview) integration.

```js {{ filename: 'astro.config.mjs', mark: [[7, 11]] }}
import clerk from '@clerk/astro'

export default defineConfig({
Expand All @@ -135,7 +137,68 @@ The `layout` property can be used to change the layout of the [`<SignIn/>`](/doc
</Tab>

<Tab>
```ts {{ filename: 'src/main.ts' }}
In JavaScript, pass the `layout` property to the `appearance` prop of the [`clerk.load()`](/docs/reference/javascript/clerk#load) method.

Use the following tabs to view the code necessary for each file.

<CodeBlockTabs options={["main.js", "index.html"]}>
```js {{ filename: 'main.js', mark: [[8, 12]], collapsible: true }}
import { Clerk } from '@clerk/clerk-js'

const clerkPubKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

const clerk = new Clerk(clerkPubKey)
await clerk.load({
appearance: {
layout: {
socialButtonsPlacement: 'bottom',
socialButtonsVariant: 'iconButton',
termsPageUrl: 'https://clerk.com/terms',
},
},
})

if (clerk.isSignedIn) {
document.getElementById('app').innerHTML = `
<div id="user-button"></div>
`

const userButtonDiv = document.getElementById('user-button')

clerk.mountUserButton(userButtonDiv)
} else {
document.getElementById('app').innerHTML = `
<div id="sign-in"></div>
`

const signInDiv = document.getElementById('sign-in')

clerk.mountSignIn(signInDiv)
}
```

```html {{ filename: 'index.html' }}
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<link rel="icon" type="image/svg+xml" href="/vite.svg" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Clerk + JavaScript App</title>
</head>
<body>
<div id="app"></div>
<script type="module" src="main.js" async crossorigin="anonymous"></script>
</body>
</html>
```
</CodeBlockTabs>
</Tab>

<Tab>
In Vue, pass the `layout` property to the `appearance` prop of the [`clerkPlugin()`](/docs/reference/vue/overview) integration.

```ts {{ filename: 'src/main.ts', mark: [[8, 12]] }}
import { createApp } from 'vue'
import App from './App.vue'
import { clerkPlugin } from '@clerk/vue'
Expand All @@ -155,7 +218,9 @@ The `layout` property can be used to change the layout of the [`<SignIn/>`](/doc
</Tab>

<Tab>
```ts {{ filename: 'nuxt.config.ts' }}
In Nuxt, pass the `layout` property to the `appearance` prop of the [`defineNuxtConfig()`](/docs/reference/nuxt/clerk-middleware) integration.

```ts {{ filename: 'nuxt.config.ts', mark: [[5, 9]] }}
export default defineNuxtConfig({
modules: ['@clerk/nuxt'],
clerk: {
Expand All @@ -170,4 +235,25 @@ The `layout` property can be used to change the layout of the [`<SignIn/>`](/doc
})
```
</Tab>

<Tab>
In Fastify, pass the `layout` property to the `appearance` prop of the [`clerkPlugin()`](/docs/reference/fastify/clerk-plugin) integration.

```ts {{ filename: 'src/main.ts', mark: [[8, 12]] }}
import Fastify from 'fastify'
import { clerkPlugin } from '@clerk/fastify'

const fastify = Fastify({ logger: true })

fastify.register(clerkPlugin, {
appearance: {
layout: {
socialButtonsPlacement: 'bottom',
socialButtonsVariant: 'iconButton',
termsPageUrl: 'https://clerk.com/terms',
},
},
})
```
</Tab>
</Tabs>
Loading