From a55bdba3b1362a0e88bbd1e5fb1871df67a99298 Mon Sep 17 00:00:00 2001
From: Pranay Kothapalli <pranaykothapalli@gmail.com>
Date: Tue, 6 Oct 2026 10:30:38 +0530
Subject: [PATCH] docs(label): add Label component page

Split out of #1544: the docs build against the published @radui/ui, so
this page can only build after a release that includes Label and a docs
bump to it. Merge after that.
---
 docs/app/docs/components/label/content.mdx    | 23 +++++++++++++++
 .../docs/components/label/docs/codeUsage.js   | 29 +++++++++++++++++++
 .../label/docs/component_api/label.tsx        | 17 +++++++++++
 .../label/docs/examples/LabelExample.tsx      | 17 +++++++++++
 docs/app/docs/components/label/page.tsx       |  7 +++++
 docs/app/docs/components/label/seo.ts         | 10 +++++++
 docs/app/docs/docsNavigationSections.tsx      |  1 +
 7 files changed, 104 insertions(+)
 create mode 100644 docs/app/docs/components/label/content.mdx
 create mode 100644 docs/app/docs/components/label/docs/codeUsage.js
 create mode 100644 docs/app/docs/components/label/docs/component_api/label.tsx
 create mode 100644 docs/app/docs/components/label/docs/examples/LabelExample.tsx
 create mode 100644 docs/app/docs/components/label/page.tsx
 create mode 100644 docs/app/docs/components/label/seo.ts

diff --git a/docs/app/docs/components/label/content.mdx b/docs/app/docs/components/label/content.mdx
new file mode 100644
index 000000000..84919a939
--- /dev/null
+++ b/docs/app/docs/components/label/content.mdx
@@ -0,0 +1,23 @@
+import Documentation from "@/components/layout/Documentation/Documentation"
+import LabelExample from "./docs/examples/LabelExample"
+import codeUsage, { api_documentation, features } from "./docs/codeUsage"
+
+<Documentation
+  title="Label"
+  description="Label renders a native label that names a form control. Use it with htmlFor, or wrap the control, so screen readers announce the control's name and clicking the label focuses it."
+>
+  <Documentation.ComponentHero codeUsage={codeUsage}>
+    <LabelExample />
+  </Documentation.ComponentHero>
+
+  <Documentation.ComponentFeatures features={features} />
+
+  <Documentation.Section title="API Documentation" as="h2">
+    <Documentation.Table
+      title="Label"
+      description={api_documentation.label.description}
+      columns={api_documentation.label.columns}
+      data={api_documentation.label.data}
+    />
+  </Documentation.Section>
+</Documentation>
diff --git a/docs/app/docs/components/label/docs/codeUsage.js b/docs/app/docs/components/label/docs/codeUsage.js
new file mode 100644
index 000000000..6ba6b430c
--- /dev/null
+++ b/docs/app/docs/components/label/docs/codeUsage.js
@@ -0,0 +1,29 @@
+import { getSourceCodeFromPath } from '@/utils/parseSourceCode';
+
+import label_api_SourceCode from './component_api/label.tsx';
+
+const example_SourceCode = await getSourceCodeFromPath('docs/app/docs/components/label/docs/examples/LabelExample.tsx');
+const scss_SourceCode = await getSourceCodeFromPath('src/components/ui/Label/label.clarity.scss');
+
+const code = {
+    javascript: {
+        code: example_SourceCode
+    },
+    scss: {
+        code: scss_SourceCode
+    }
+};
+
+export const api_documentation = {
+    label: label_api_SourceCode
+};
+
+export const features = [
+    "Native <label>, so clicking it focuses or toggles the control it names",
+    "Name a control with htmlFor, or by wrapping the control",
+    "Double-clicking the label doesn't select its text; nested controls still get their own clicks",
+    "asChild to render your own element with the label's props",
+    "Unstyled by default, with Clarity and baremetal styles available"
+];
+
+export default code;
diff --git a/docs/app/docs/components/label/docs/component_api/label.tsx b/docs/app/docs/components/label/docs/component_api/label.tsx
new file mode 100644
index 000000000..1d0b65658
--- /dev/null
+++ b/docs/app/docs/components/label/docs/component_api/label.tsx
@@ -0,0 +1,17 @@
+const data = {
+    name: "Label",
+    description: "Renders a native <label> that names a form control, either through htmlFor or by wrapping the control.",
+    columns: [
+        { name: "Prop", id: "prop" },
+        { name: "Type", id: "type" },
+        { name: "Default", id: "default" }
+    ],
+    data: [
+        { prop: { name: "htmlFor", info_tooltips: "The id of the form control this label names." }, type: "string", default: "--" },
+        { prop: { name: "asChild", info_tooltips: "Render the child element instead of a <label>, merging the label's props onto it." }, type: "boolean", default: "false" },
+        { prop: { name: "customRootClass", info_tooltips: "Class namespace for the root class (e.g. \"acme\" gives acme-label)." }, type: "string", default: "''" },
+        { prop: { name: "className", info_tooltips: "Additional CSS class names." }, type: "string", default: "''" }
+    ]
+};
+
+export default data;
diff --git a/docs/app/docs/components/label/docs/examples/LabelExample.tsx b/docs/app/docs/components/label/docs/examples/LabelExample.tsx
new file mode 100644
index 000000000..947174843
--- /dev/null
+++ b/docs/app/docs/components/label/docs/examples/LabelExample.tsx
@@ -0,0 +1,17 @@
+'use client'
+
+import Label from "@radui/ui/Label"
+
+const LabelExample = () => (
+    <div className="flex w-64 flex-col gap-2">
+        <Label htmlFor="label-example-email">Email address</Label>
+        <input
+            id="label-example-email"
+            type="email"
+            placeholder="you@example.com"
+            className="rounded-md border border-gray-400 bg-gray-50 px-3 py-2 text-sm text-gray-1000"
+        />
+    </div>
+)
+
+export default LabelExample
diff --git a/docs/app/docs/components/label/page.tsx b/docs/app/docs/components/label/page.tsx
new file mode 100644
index 000000000..87be3c748
--- /dev/null
+++ b/docs/app/docs/components/label/page.tsx
@@ -0,0 +1,7 @@
+import { createDocsPage } from '@/components/docsPage/createDocsPage'
+import metadata from './seo'
+import Content from './content.mdx'
+
+export { metadata }
+
+export default createDocsPage(Content)
diff --git a/docs/app/docs/components/label/seo.ts b/docs/app/docs/components/label/seo.ts
new file mode 100644
index 000000000..8e70f2a3b
--- /dev/null
+++ b/docs/app/docs/components/label/seo.ts
@@ -0,0 +1,10 @@
+import generateSeoMetadata from "@/utils/seo/generateSeoMetadata"
+
+const metadata = generateSeoMetadata({
+    title: "Label - Rad UI",
+    description: "Accessible, headless React Label component. Names form controls with a native label, supports asChild, and avoids text selection on double-click.",
+    keywords: ["React Label", "headless label", "accessible label", "form label component", "React label component"],
+    canonicalUrl: "https://www.rad-ui.com/docs/components/label"
+});
+
+export default metadata
diff --git a/docs/app/docs/docsNavigationSections.tsx b/docs/app/docs/docsNavigationSections.tsx
index a68711530..72c90c383 100644
--- a/docs/app/docs/docsNavigationSections.tsx
+++ b/docs/app/docs/docsNavigationSections.tsx
@@ -54,6 +54,7 @@ export const docsNavigationSections = [
             { title:"Heading", path:"/docs/components/heading" },
             { title:"HoverCard", path:"/docs/components/hover-card", is_preview:true },
             { title:"Kbd", path:"/docs/components/kbd" },
+            { title:"Label", path:"/docs/components/label", is_preview:true },
             { title:"Link", path:"/docs/components/link", is_preview:true },
             { title:"LiveRegion", path:"/docs/components/live-region", is_preview:true },
             { title:"Menubar", path:"/docs/components/menubar", is_preview:true },