Skip to content

feat: add docs for ory elements v1.2 #2361

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
jonas-jonas wants to merge 5 commits into
base: master
Choose a base branch
from
+1,101 −190
Open

feat: add docs for ory elements v1.2 #2361

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
476119e
feat: add docs for ory elements v1.2
jonas-jonas Nov 24, 2025
0b675f3
Apply suggestions from code review
jonas-jonas Nov 26, 2025
83f9863
Merge remote-tracking branch 'origin/master' into jonas-jonas/oryElem…
jonas-jonas Nov 26, 2025
e402664
chore: u
jonas-jonas Nov 26, 2025
4e6e4d3
chore: u
jonas-jonas Nov 26, 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
37 changes: 34 additions & 3 deletions docs/elements/guides/05_migration_0x.mdx → docs/elements/guides/05_upgrading.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,40 @@
---
id: migration-0x
title: Migration from Ory Elements 0.x to 1.x
sidebar_label: Migration from 0.x to 1.x
id: upgrade
title: Upgrade Ory Elements
sidebar_label: Upgrading
---

# Upgrade Guide

## Ory Elements 1.1.0 to 1.2.0 upgrade guide

This guide will show you how to migrate from Ory Elements 1.1.0 to 1.2.0.

If you are current overriding components using the `components` prop, you may need to update your overrides to pass the correct
props to your custom components.

- `Node.Button`: Now receives additional props:
- `isSubmitting`: This prop indicates whether this button was used to submit the form and the form is currently submitting.
- `buttonProps`: This prop contains all other button-related props that should be spread onto the button element.
- `Node.Input`: Now receives additional props:
- `inputProps`: This prop contains all other input-related props that should be spread onto the input element.
- `Node.Checkbox`:
- `inputProps`: This prop contains all other checkbox-related props that should be spread onto the checkbox input element.
- `Node.ConsentScopeCheckbox`:
- `inputProps`: This prop contains all other checkbox-related props that should be spread onto the checkbox input element.
- `Node.Label`:
- `fieldError`: This prop contains the error message associated with the field, if any.
- Settings Pages:
- Each settings section now similarly receives the nodes with a `buttonProps` or `inputProps` prop, depending on the type of
node.

## Fixes

- If you were using the `RecoveryCodesSettings` component, there was a typo in the prop name for regenerating codes. The correct
prop name is now `regenerateButton` instead of `regnerateButton`.

## Ory Elements 0.x to 1.x Upgrade Guide

This guide will show you how to migrate from Ory Elements 0.x to 1.x.

Ory Elements 1.0 is a complete rewrite of the Ory Elements 0.x library. It is not backwards compatible with 0.x.
Expand Down
8 changes: 4 additions & 4 deletions docs/elements/reference/@ory/elements-react/functions/OryCardValidationMessages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,10 @@ See also [useOryFlow](useOryFlow.md)

## Parameters

| Parameter | Type | Description |
| ------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `__namedParameters` | \{ `hiddenMessageIds?`: `number`[]; \} | - |
| `__namedParameters.hiddenMessageIds?` | `number`[] | An array of message IDs that should be hidden. This is useful for hiding specific messages that are not relevant to the user or are rendered elsewhere. If not provided, the default list of message IDs to hide will be used. **Default** `[1040009, 1060003, 1080003, 1010004, 1010014, 1040005, 1010016, 1010003]` **See** https://www.ory.com/docs/kratos/concepts/ui-messages |
| Parameter | Type | Description |
| ------------------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `__namedParameters` | \{ `hiddenMessageIds?`: `number`[]; \} | - |
| `__namedParameters.hiddenMessageIds?` | `number`[] | An array of message IDs that should be hidden. This is useful for hiding specific messages that are not relevant to the user or are rendered elsewhere. If not provided, the default list of message IDs to hide will be used. **Default** `[1040009, 1060003, 1080003, 1010004, 1010014, 1040005, 1010016, 1010003]` **See** https://www.ory.sh/docs/kratos/concepts/ui-messages |

## Returns

Expand Down
32 changes: 16 additions & 16 deletions docs/elements/reference/@ory/elements-react/functions/OrySettingsFormSection.md
View file
Open in desktop

Large diffs are not rendered by default.

15 changes: 15 additions & 0 deletions docs/elements/reference/@ory/elements-react/functions/isUiNodeAnchor.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# isUiNodeAnchor()

```ts
function isUiNodeAnchor(node: UiNode): node is UiNodeAnchor
```

## Parameters

| Parameter | Type |
| --------- | -------- |
| `node` | `UiNode` |

## Returns

`node is UiNodeAnchor`
15 changes: 15 additions & 0 deletions docs/elements/reference/@ory/elements-react/functions/isUiNodeDiv.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# isUiNodeDiv()

```ts
function isUiNodeDiv(node: UiNode): node is UiNodeDiv
```

## Parameters

| Parameter | Type |
| --------- | -------- |
| `node` | `UiNode` |

## Returns

`node is UiNodeDiv`
15 changes: 15 additions & 0 deletions docs/elements/reference/@ory/elements-react/functions/isUiNodeImage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# isUiNodeImage()

```ts
function isUiNodeImage(node: UiNode): node is UiNodeImage
```

## Parameters

| Parameter | Type |
| --------- | -------- |
| `node` | `UiNode` |

## Returns

`node is UiNodeImage`
15 changes: 15 additions & 0 deletions docs/elements/reference/@ory/elements-react/functions/isUiNodeInput.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# isUiNodeInput()

```ts
function isUiNodeInput(node: UiNode): node is UiNodeInput
```

## Parameters

| Parameter | Type |
| --------- | -------- |
| `node` | `UiNode` |

## Returns

`node is UiNodeInput`
15 changes: 15 additions & 0 deletions docs/elements/reference/@ory/elements-react/functions/isUiNodeScript.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# isUiNodeScript()

```ts
function isUiNodeScript(node: UiNode): node is UiNodeScript
```

## Parameters

| Parameter | Type |
| --------- | -------- |
| `node` | `UiNode` |

## Returns

`node is UiNodeScript`
15 changes: 15 additions & 0 deletions docs/elements/reference/@ory/elements-react/functions/isUiNodeText.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# isUiNodeText()

```ts
function isUiNodeText(node: UiNode): node is UiNodeText
```

## Parameters

| Parameter | Type |
| --------- | -------- |
| `node` | `UiNode` |

## Returns

`node is UiNodeText`
16 changes: 16 additions & 0 deletions docs/elements/reference/@ory/elements-react/functions/resolvePlaceholder.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# resolvePlaceholder()

```ts
function resolvePlaceholder(text: UiText, intl: IntlShape): string
```

## Parameters

| Parameter | Type |
| --------- | ----------- |
| `text` | `UiText` |
| `intl` | `IntlShape` |

## Returns

`string`
42 changes: 42 additions & 0 deletions docs/elements/reference/@ory/elements-react/functions/useResendCode.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# useResendCode()

```ts
function useResendCode(): {
resendCode: () => void
resendCodeNode: undefined | UiNode
}
```

useResendCode provides a callback to trigger a code resend in the current flow.

You may use this hook to implement a "Resend Code" button in your forms.

If the current flow does not support code resending, `resendCodeNode` will be `undefined` and `resendCode` will be a no-op.

Example:

```tsx
const { resendCode, resendCodeNode } = useResendCode();

return (
{resendCodeNode && (
<button onClick={resendCode}>Resend Code</button>
)}
)
```

## Returns

```ts
{
resendCode: () => void;
resendCodeNode: undefined | UiNode;
}
```

the callback to trigger a code resend

| Name | Type | Default value |
| ---------------- | ----------------------- | -------------- |
| `resendCode()` | () => `void` | `handleResend` |
| `resendCodeNode` | `undefined` \| `UiNode` | - |
31 changes: 25 additions & 6 deletions ...s/reference/@ory/elements-react/index.mdx → ...ts/reference/@ory/elements-react/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,3 @@
---
id: index
title: "@ory/elements-react"
sidebar_label: "@ory/elements-react"
---

# @ory/elements-react

This package provides the core functionality for Ory Elements in React.
Expand Down Expand Up @@ -33,6 +27,7 @@ This package provides the core functionality for Ory Elements in React.
- [FormStateAction](type-aliases/FormStateAction.md)
- [FormValues](type-aliases/FormValues.md)
- [IntlConfig](type-aliases/IntlConfig.md)
- [NodeProps](type-aliases/NodeProps.md)
- [OnSubmitHandlerProps](type-aliases/OnSubmitHandlerProps.md)
- [OryCardAuthMethodListItemProps](type-aliases/OryCardAuthMethodListItemProps.md)
- [OryCardContentProps](type-aliases/OryCardContentProps.md)
Expand All @@ -49,12 +44,17 @@ This package provides the core functionality for Ory Elements in React.
- [OryFormSectionFooterProps](type-aliases/OryFormSectionFooterProps.md)
- [OryFormSsoRootProps](type-aliases/OryFormSsoRootProps.md)
- [OryNodeAnchorProps](type-aliases/OryNodeAnchorProps.md)
- [OryNodeButtonButtonProps](type-aliases/OryNodeButtonButtonProps.md)
- [OryNodeButtonProps](type-aliases/OryNodeButtonProps.md)
- [OryNodeCaptchaProps](type-aliases/OryNodeCaptchaProps.md)
- [OryNodeCheckboxInputProps](type-aliases/OryNodeCheckboxInputProps.md)
- [OryNodeCheckboxProps](type-aliases/OryNodeCheckboxProps.md)
- [OryNodeConsentScopeCheckboxProps](type-aliases/OryNodeConsentScopeCheckboxProps.md)
- [OryNodeImageProps](type-aliases/OryNodeImageProps.md)
- [OryNodeInputInputProps](type-aliases/OryNodeInputInputProps.md)
- [OryNodeInputProps](type-aliases/OryNodeInputProps.md)
- [OryNodeLabelProps](type-aliases/OryNodeLabelProps.md)
- [OryNodeSettingsButton](type-aliases/OryNodeSettingsButton.md)
- [OryNodeSsoButtonProps](type-aliases/OryNodeSsoButtonProps.md)
- [OryNodeTextProps](type-aliases/OryNodeTextProps.md)
- [OryPageHeaderProps](type-aliases/OryPageHeaderProps.md)
Expand All @@ -66,13 +66,31 @@ This package provides the core functionality for Ory Elements in React.
- [OrySettingsTotpProps](type-aliases/OrySettingsTotpProps.md)
- [OrySettingsWebauthnProps](type-aliases/OrySettingsWebauthnProps.md)
- [OryToastProps](type-aliases/OryToastProps.md)
- [UiNodeAnchor](type-aliases/UiNodeAnchor.md)
- [UiNodeDiv](type-aliases/UiNodeDiv.md)
- [UiNodeFixed](type-aliases/UiNodeFixed.md)
- [UiNodeImage](type-aliases/UiNodeImage.md)
- [UiNodeInput](type-aliases/UiNodeInput.md)
- [UiNodeScript](type-aliases/UiNodeScript.md)
- [UiNodeText](type-aliases/UiNodeText.md)

## Variables

- [OryLocales](variables/OryLocales.md)

## Functions

- [isUiNodeAnchor](functions/isUiNodeAnchor.md)
- [isUiNodeDiv](functions/isUiNodeDiv.md)
- [isUiNodeImage](functions/isUiNodeImage.md)
- [isUiNodeInput](functions/isUiNodeInput.md)
- [isUiNodeScript](functions/isUiNodeScript.md)
- [isUiNodeText](functions/isUiNodeText.md)
- [resolvePlaceholder](functions/resolvePlaceholder.md)

## Components

- [Node](variables/Node.md)
- [OryCard](functions/OryCard.md)
- [OryCardContent](functions/OryCardContent.md)
- [OryCardFooter](functions/OryCardFooter.md)
Expand All @@ -96,6 +114,7 @@ This package provides the core functionality for Ory Elements in React.
- [useNodeSorter](functions/useNodeSorter.md)
- [useOryConfiguration](functions/useOryConfiguration.md)
- [useOryFlow](functions/useOryFlow.md)
- [useResendCode](functions/useResendCode.md)

## Utilities

Expand Down
24 changes: 13 additions & 11 deletions docs/elements/reference/@ory/elements-react/theme/functions/DefaultButtonSocial.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,25 +3,27 @@
```ts
function DefaultButtonSocial(props: {
attributes: UiNodeInputAttributes
buttonProps: OryNodeButtonButtonProps
isSubmitting: boolean
logos?: Record<string, ElementType>
node: UiNode
onClick?: () => void
showLabel?: boolean
node: UiNodeInput
provider: string
}): Element
```

The default implementation of a social button for Ory SSO. It renders a button with a logo and an optional label.

## Parameters

| Parameter | Type | Description |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `props` | \{ `attributes`: `UiNodeInputAttributes`; `logos?`: `Record`\<`string`, `ElementType`\>; `node`: `UiNode`; `onClick?`: () => `void`; `showLabel?`: `boolean`; \} | The props for the DefaultButtonSocial component. |
| `props.attributes` | `UiNodeInputAttributes` | - |
| `props.logos?` | `Record`\<`string`, `ElementType`\> | Logos to use for the social buttons. If not provided, the default logos will be used. |
| `props.node` | `UiNode` | - |
| `props.onClick?` | () => `void` | - |
| `props.showLabel?` | `boolean` | Whether to show the label next to the logo. If not provided, it will be determined based on the number of SSO nodes. |
| Parameter | Type | Description |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `props` | \{ `attributes`: `UiNodeInputAttributes`; `buttonProps`: [`OryNodeButtonButtonProps`](../../type-aliases/OryNodeButtonButtonProps.md); `isSubmitting`: `boolean`; `logos?`: `Record`\<`string`, `ElementType`\>; `node`: [`UiNodeInput`](../../type-aliases/UiNodeInput.md); `provider`: `string`; \} | The props for the DefaultButtonSocial component. |
| `props.attributes` | `UiNodeInputAttributes` | **Deprecated** Use node.attributes instead. |
| `props.buttonProps` | [`OryNodeButtonButtonProps`](../../type-aliases/OryNodeButtonButtonProps.md) | - |
| `props.isSubmitting` | `boolean` | - |
| `props.logos?` | `Record`\<`string`, `ElementType`\> | Logos to use for the social buttons. If not provided, the default logos will be used. |
| `props.node` | [`UiNodeInput`](../../type-aliases/UiNodeInput.md) | - |
| `props.provider` | `string` | - |

## Returns

Expand Down
13 changes: 8 additions & 5 deletions docs/elements/reference/@ory/elements-react/theme/functions/DefaultCard.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,20 @@
# `<DefaultCard />`

```ts
function DefaultCard(props: { children?: ReactNode }): Element
function DefaultCard(
props: {
children?: ReactNode
} & Omit<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">,
): Element
```

The DefaultCard component is a styled container that serves as the main card layout for Ory Elements.

## Parameters

| Parameter | Type | Description |
| ----------------- | ------------------------------- | --------------------------------------------- |
| `props` | \{ `children?`: `ReactNode`; \} | The properties for the DefaultCard component. |
| `props.children?` | `ReactNode` | - |
| Parameter | Type | Description |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| `props` | \{ `children?`: `ReactNode`; \} & `Omit`\<`DetailedHTMLProps`\<`HTMLAttributes`\<`HTMLDivElement`\>, `HTMLDivElement`\>, `"ref"`\> | The properties for the DefaultCard component. |

## Returns

Expand Down
Loading
Loading