feat: document transient payload passthrough in elements

Author: jonas-jonas

docs/elements/guides/30_transient_payloads.mdx

@@ -0,0 +1,73 @@
+---
+id: transient-payload
+title: Transient Payload passthrough
+sidebar_label: Transient Payload
+---
+
+Transient payload is an Ory Kratos concept, that allows users of the APIs to pass data through to webhooks. All self-service Kratos flows support transient payloads, and they are passed through to the webhooks as JSON objects. This allows you to use the data in your webhooks, for example to customize the user experience or to trigger specific actions based on the data.
+
+Ory Elements allows defining transient payloads on the self-service flow components. To do this, you can use the `transientPayload` prop on the self-service flow components. The value of this prop should be an object that contains the data you want to pass through to the webhooks or a function that returns such an object. The data will be passed through to the webhooks as JSON objects.
+
+
+## Static Transient Payload
+
+In this example, we define a static transient payload that contains the user's preferred language. This data will be passed through to the webhooks as a JSON object.
+
+```tsx
+import { Registration } from "@ory/elements-react/theme"
+import { getRegistrationFlow, OryPageParams } from "@ory/nextjs/app"
+
+import config from "@/ory.config"
+import { headers } from "next/headers"
+
+export default async function RegistrationPage(props: OryPageParams) {
+  const flow = await getRegistrationFlow(config, props.searchParams)
+
+  const language = (await headers()).get("Accept-Language")
+
+  if (!flow) {
+    return null
+  }
+
+  return (
+    <Registration
+      flow={flow}
+      config={config}
+      components={{
+        Card: {},
+      }}
+      transientPayload={{
+        language
+      }}
+    />
+  )
+}
+
+```
+
+## Dynamic Transient Payload
+
+In this example, we define a dynamic transient payload that contains the user's preferred language. The function is called, when the user submits the form, and the API request is made. This allows you to pass dynamic data to the webhooks, based on the user's input or other factors.
+
+```tsx
+"use client"
+
+import { Registration } from "@ory/elements-react/theme"
+import { RegistrationFlow } from "@ory/client-fetch"
+import config from "@/ory.config"
+
+export function RegistrationWithPayload({ flow }: { flow: RegistrationFlow }) {
+  return <Registration
+    flow={flow}
+    config={config}
+    transientPayload={(formValues) => {
+      const referalCode = localStorage.getItem("referal-code")
+      return {
+        referalCode,
+      }
+    }}
+  />
+}
+```
+
+The function also receives the form values as an argument, which allows you to use the user's input to determine the transient payload. In this example, we are retrieving a referral code from local storage and passing it through to the webhooks.