chore: Updates docs from Protect -> Show #2916

alexcarpenter · 2025-12-19T18:36:37Z

🔎 Previews:

What does this solve?

What changed?

vercel · 2025-12-19T18:36:41Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
clerk-docs	Ready	Preview	Jan 16, 2026 3:20am

alexisintech · 2026-01-12T23:06:03Z

how can I test this? is there a snapshot or something? 👀 I need to test for all the SDKs @jacekradko @alexcarpenter

alexcarpenter · 2026-01-12T23:09:51Z

@alexisintech the dashboard is using the updated APIs if you have that pulled down and running.

or install @clerk/nextjs@canary too I think right @jacekradko?

brkalow

Documentation Review

I reviewed this PR against the source code changes in clerk/javascript@f1f1d09. Found a few issues noted in line comments below.

Summary

Issue	Severity	Lines
Wrong `plan` instead of `feature` in Feature examples	Critical	850-858, 873-882
Missing `'signed-out'` in Properties type	Medium	1117
Inconsistent prop patterns (shorthand vs `when`)	Needs Clarification	Multiple

docs/reference/components/control/show.mdx

manovotny · 2026-01-13T23:19:19Z

docs/_partials/billing/checking-permission-using-show.mdx

-      <Protect
-        permission="premium_access:manage"
+      <Show
+        when={{ permission: 'premium_access:manage' }}


Should all of these follow has syntax?

https://github.com/clerk/clerk-docs/blob/main/docs/_partials/billing/checking-permission-using-has-function.mdx

Meaning, should all of these be org:premium_access:manage instead?

i believe i remember that you keep or omit org: prefix

just tested this and yes, you can omit the org: prefix - however, we can be consistent across the docs and add it, it doesn't hurt.

manovotny · 2026-01-13T23:23:49Z

docs/guides/billing/for-b2b.mdx

+You can use Clerk's Features, Plans, and Permissions to gate access to content using [authorization checks](!authorization-check). There are a few ways to do this, but the recommended approach is to either use the [`has()`](/docs/reference/backend/types/auth-object#has) method or the [`<Show>`](/docs/reference/components/control/show) component.

-The `has()` method is available for any JavaScript-based framework, while `<Protect>` is a component, and therefore, is only available for React-based frameworks.
+The `has()` method is available for any JavaScript-based framework, while `<Show>` is a component, and therefore, is only available for React-based frameworks.


while <Show> is a component, and therefore, is only available for React-based frameworks.

Is this true since we have examples for Astro, Vue, and Nuxt?

If it needs to be reworded, its in docs/guides/billing/for-b2c.mdx too.

nice catch!! updated: b8aa71a

manovotny · 2026-01-13T23:38:10Z

docs/_partials/billing/checking-feature-using-show.mdx

  ```astro {{ filename: 'src/pages/protected-premium-content.astro' }}
  ---
-  import { Protect } from '@clerk/astro/react'
+  import { Show } from '@clerk/astro/react'


I’m a novice at Astro, so I could be completely wrong here.  

But should these be importing @clerk/astro/components instead and using slot="fallback" instead?  

See here → https://clerk.com/docs/astro/reference/components/control/protect

  If true, we’ll want to update these too:  

docs/_partials/billing/checking-plan-using-show.mdx

docs/_partials/billing/checking-permission-using-show.mdx

it will be from @clerk/astro/components if the user isn't using react. if they try to use @clerk/astro/react, they'll get an error, because they haven't configured react.
if they've configured their astro app to use react, they can use @clerk/astro/react.

we should be using the @clerk/astro/components import as we usually assume the user followed the clerk astro quickstart guide, which does not configure react

updated to use @clerk/astro/components as the import b8aa71a

manovotny · 2026-01-13T23:42:02Z

docs/guides/development/custom-flows/account-updates/user-impersonation.mdx


      1. Create the `dashboard/` directory.
-      1. In the `dashboard/` directory, create a `_layout.tsx` file with the following code. The [`useAuth()`](/docs/reference/hooks/use-auth) hook is used to access the user's authentication state. If the user is already signed in, they'll be redirected to the home page. The [`<Protect>`](/docs/reference/components/control/protect) component is used to ensure that only users with the `org:dashboard:access` Permission can access it. You can modify the `permission` attribute to fit your use case.
+      1. In the `dashboard/` directory, create a `_layout.tsx` file with the following code. The [`useAuth()`](/docs/reference/hooks/use-auth) hook is used to access the user's authentication state. If the user is already signed in, they'll be redirected to the home page. The [`<Show>`](/docs/reference/components/control/show) component is used to ensure that only users with the `org:dashboard:access` Permission can access it. You can modify the `permission` attribute to fit your use case.


You can modify the permission attribute to fit your use case.

Should this say when={{ permission: ... }} instead?

oo good catch - i looked for other instances of this and fixed those as well: 01d4e46

manovotny · 2026-01-13T23:47:48Z

docs/reference/components/control/show.mdx

-title: '`<Protect>`'
-description: The Protect component protects content or even entire routes based on authentication, and optionally, authorization. It only renders its children when the current user is signed-in, and if performing authorization checks, if the user has been granted a specific type of access control (Role, Permission, Feature, or Plan).
+title: '`<Show>`'
+description: The Show component protects content or even entire routes based on authentication, and optionally, authorization. It only renders its children when the current user is signed-in, and if performing authorization checks, if the user has been granted a specific type of access control (Role, Permission, Feature, or Plan).


It only renders its children when the current user is signed-in

I think this needs to be reworded. According to clerk/javascript@f1f1d09, <Show when="signed-out"> appears to be supported.

If true, other coding examples below may need to be updated too.

nice catch! i've just removed that sentence and simplified the description: c1a222c

- Fix react-router and tanstack Feature examples using plan instead of feature - Add 'signed-out' to when prop type definition - Standardize Astro/Vue/Nuxt examples to use when prop instead of shorthand - Replace condition prop with when for callback function examples

alexisintech · 2026-01-14T21:44:56Z

@manovotny thanks for the eyes on this!! i haven't approved it yet because i still have to test all of the code - my review was a basic overview. once i test the functionality with all the sdk's i'll ensure all these examples are working, and also address the feedback you've left (great catches!)

alexisintech · 2026-01-14T22:06:42Z

with astro sdk, <show> is throwing this error when trying to be used with a fallback:

i tried adding and removing the slot="fallback" but it makes no difference

<show> works on the index page without a fallback, so i'm assuming its something with the fallback here - the syntax must not be correct or the sdk might have a bug

alexisintech · 2026-01-14T23:26:45Z

alrighty, tested all sdk's and they're looking great except for the astro bug i posted, and then just need to test expo - which is being worked on by chris right now!

jacekradko · 2026-01-16T03:11:00Z

@alexisintech Can you try this syntax for the astro fallback:

<Show when={{ plan: 'bronze' }}>
    <p slot="fallback">Only subscribers to the Bronze plan can access this content.</p>
    <h1>Exclusive Bronze Content</h1>
    <p>This content is only visible to Bronze subscribers.</p>
</Show>

vercel bot had a problem deploying to Preview December 19, 2025 18:37 Failure

vercel bot had a problem deploying to Preview December 19, 2025 21:05 Failure

vercel bot had a problem deploying to Preview December 19, 2025 21:10 Failure

vercel bot deployed to Preview December 19, 2025 21:20 View deployment

vercel bot deployed to Preview December 19, 2025 21:52 View deployment

vercel bot deployed to Preview December 19, 2025 22:03 View deployment

vercel bot deployed to Preview January 5, 2026 23:04 View deployment

vercel bot deployed to Preview January 10, 2026 02:35 View deployment

jacekradko force-pushed the alexcarpenter/protect-show branch from 997960e to 6f8c6b7 Compare January 12, 2026 18:54

vercel bot deployed to Preview January 12, 2026 18:55 View deployment

jacekradko marked this pull request as ready for review January 12, 2026 19:15

jacekradko requested a review from a team as a code owner January 12, 2026 19:15

vercel bot deployed to Preview January 12, 2026 19:17 View deployment

vercel bot had a problem deploying to Preview January 12, 2026 19:30 Failure

vercel bot had a problem deploying to Preview January 12, 2026 19:56 Failure

jacekradko force-pushed the alexcarpenter/protect-show branch from cf2b731 to fe3906b Compare January 12, 2026 21:37

vercel bot deployed to Preview January 12, 2026 21:38 View deployment

alexisintech self-assigned this Jan 12, 2026

vercel bot deployed to Preview January 12, 2026 23:07 View deployment

brkalow reviewed Jan 13, 2026

View reviewed changes

docs/reference/components/control/show.mdx Outdated Show resolved Hide resolved

docs/reference/components/control/show.mdx Show resolved Hide resolved

docs/reference/components/control/show.mdx Outdated Show resolved Hide resolved

brkalow reviewed Jan 13, 2026

View reviewed changes

docs/reference/components/control/show.mdx Outdated Show resolved Hide resolved

docs/reference/components/control/show.mdx Outdated Show resolved Hide resolved

docs/reference/components/control/show.mdx Outdated Show resolved Hide resolved

vercel bot deployed to Preview January 13, 2026 03:55 View deployment

manovotny reviewed Jan 13, 2026

View reviewed changes

alexcarpenter and others added 3 commits January 13, 2026 20:31

chore: Updates docs from Protect -> Show

aaf6eff

additional updates

235b77c

update file location

393d8fb

jacekradko and others added 8 commits January 13, 2026 20:31

fix manifest

be74290

more conversions

b241ef6

wip

ae778ef

update Show props

c2882e2

fix Show component imports in code examples

27e5ee2

fix: Vue template syntax and formatting issues

faa4f13

docs review

80b94ee

jacekradko force-pushed the alexcarpenter/protect-show branch from ab03639 to ddbd113 Compare January 14, 2026 02:32

vercel bot deployed to Preview January 14, 2026 02:33 View deployment

docs review - tested sdks

b8aa71a

vercel bot deployed to Preview January 14, 2026 23:23 View deployment

alexisintech added 2 commits January 14, 2026 16:23

fix prop references

01d4e46

fix show component page description

c1a222c

vercel bot deployed to Preview January 14, 2026 23:26 View deployment

Merge core-3 into alexcarpenter/protect-show

2185118

vercel bot deployed to Preview January 16, 2026 03:20 View deployment

chore: Updates docs from Protect -> Show #2916

Are you sure you want to change the base?

chore: Updates docs from Protect -> Show #2916

Uh oh!

Conversation

alexcarpenter commented Dec 19, 2025 • edited by jacekradko Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔎 Previews:

What does this solve?

What changed?

Uh oh!

vercel bot commented Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alexisintech commented Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alexcarpenter commented Jan 12, 2026

Uh oh!

brkalow left a comment

Choose a reason for hiding this comment

Documentation Review

Summary

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexisintech commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alexisintech commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alexisintech commented Jan 14, 2026

Uh oh!

jacekradko commented Jan 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

alexcarpenter commented Dec 19, 2025 •

edited by jacekradko

Loading

vercel bot commented Dec 19, 2025 •

edited

Loading

alexisintech commented Jan 12, 2026 •

edited

Loading

alexisintech commented Jan 14, 2026 •

edited

Loading

alexisintech commented Jan 14, 2026 •

edited

Loading