.',
+ },
+ {
+ name: 'hasBorder',
+ type: 'boolean',
+ description:
+ 'Whether to render a border below the PageHeader. This border will NOT be rendered if the PageHeader has a `PageHeader.Navigation` child that is not hidden at the current breakpoint.',
+ required: false,
+ },
+ ],
+ subcomponents: [
+ {
+ name: 'PageHeader.ContextArea',
+ props: [
+ {name: 'className', type: 'string | undefined', description: 'CSS string', required: false},
+ {
+ name: 'hidden',
+ type: '| boolean | { narrow?: boolean regular?: boolean wide?: boolean }',
+ defaultValue: 'false',
+ description: 'Whether the content is hidden.',
+ required: false,
+ },
+ ],
+ displayName: 'ContextArea',
+ },
+ {
+ name: 'PageHeader.ParentLink',
+ props: [
+ {
+ name: 'aria-label',
+ type: 'string | undefined',
+ description: 'A unique label for the rendered landmark',
+ required: false,
+ },
+ {name: 'className', type: 'string | undefined', description: 'CSS string', required: false},
+ {name: 'href', type: 'string', description: 'The URL to link to.', required: false},
+ {
+ name: 'hidden',
+ type: '| boolean | { narrow?: boolean regular?: boolean wide?: boolean }',
+ defaultValue: '`{ narrow: false regular: true wide: true }`',
+ description: 'Whether the parent link is hidden.',
+ required: false,
+ },
+ ],
+ displayName: 'ParentLink',
+ },
+ {
+ name: 'PageHeader.ContextBar',
+ props: [
+ {name: 'className', type: 'string | undefined', description: 'CSS string', required: false},
+ {
+ name: 'hidden',
+ type: '| boolean | { narrow?: boolean regular?: boolean wide?: boolean }',
+ defaultValue: 'false',
+ description: 'Whether the content is hidden.',
+ required: false,
+ },
+ ],
+ displayName: 'ContextBar',
+ },
+ {
+ name: 'PageHeader.ContextAreaActions',
+ props: [
+ {name: 'className', type: 'string | undefined', description: 'CSS string', required: false},
+ {
+ name: 'hidden',
+ type: '| boolean | { narrow?: boolean regular?: boolean wide?: boolean }',
+ defaultValue: 'false',
+ description: 'Whether the content is hidden.',
+ required: false,
+ },
+ ],
+ displayName: 'ContextAreaActions',
+ },
+ {
+ name: 'PageHeader.TitleArea',
+ props: [
+ {name: 'className', type: 'string | undefined', description: 'CSS string', required: false},
+ {
+ name: 'hidden',
+ type: '| boolean | { narrow?: boolean regular?: boolean wide?: boolean }',
+ defaultValue: 'false',
+ description: 'Whether the content is hidden.',
+ required: false,
+ },
+ {
+ name: 'variant',
+ type: "| 'subtitle' | 'medium' | 'large' | { narrow?: | 'subtitle' | 'medium' | 'large' regular?: | 'subtitle' | 'medium' | 'large' wide?: | 'subtitle' | 'medium' | 'large' }",
+ defaultValue: 'medium',
+ description:
+ 'Default title (medium) is the most common page title size. Use for static titles in most situations.\nLarge variant should be used for user-generated content such as issues, pull requests, or discussions.\nSubtitle variant can be used when a PageHeader.Title is already present in the page, such as in a SplitPageLayout.',
+ required: false,
+ },
+ ],
+ displayName: 'TitleArea',
+ },
+ {
+ name: 'PageHeader.LeadingAction',
+ props: [
+ {name: 'className', type: 'string | undefined', description: 'CSS string', required: false},
+ {
+ name: 'hidden',
+ type: '| boolean | { narrow?: boolean regular?: boolean wide?: boolean }',
+ defaultValue: 'false',
+ description: 'Whether the content is hidden.',
+ required: false,
+ },
+ ],
+ displayName: 'LeadingAction',
+ },
+ {
+ name: 'PageHeader.LeadingVisual',
+ props: [
+ {name: 'className', type: 'string | undefined', description: 'CSS string', required: false},
+ {
+ name: 'hidden',
+ type: '| boolean | { narrow?: boolean regular?: boolean wide?: boolean }',
+ defaultValue: 'false',
+ description: 'Whether the content is hidden.',
+ required: false,
+ },
+ ],
+ displayName: 'LeadingVisual',
+ },
+ {
+ name: 'PageHeader.Title',
+ props: [
+ {name: 'className', type: 'string | undefined', description: 'CSS string', required: false},
+ {
+ name: 'hidden',
+ type: '| boolean | { narrow?: boolean regular?: boolean wide?: boolean }',
+ defaultValue: 'false',
+ description: 'Whether the content is hidden.',
+ required: false,
+ },
+ {
+ name: 'as',
+ type: "'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'",
+ defaultValue: '"h2"',
+ description: 'Heading level to render. Standard heading attributes are forwarded to the rendered heading.',
+ required: false,
+ },
+ ],
+ displayName: 'Title',
+ },
+ {
+ name: 'PageHeader.TrailingVisual',
+ props: [
+ {name: 'className', type: 'string | undefined', description: 'CSS string', required: false},
+ {
+ name: 'hidden',
+ type: '| boolean | { narrow?: boolean regular?: boolean wide?: boolean }',
+ defaultValue: 'false',
+ description: 'Whether the content is hidden.',
+ required: false,
+ },
+ ],
+ displayName: 'TrailingVisual',
+ },
+ {
+ name: 'PageHeader.TrailingAction',
+ props: [
+ {name: 'className', type: 'string | undefined', description: 'CSS string', required: false},
+ {
+ name: 'hidden',
+ type: '| boolean | { narrow?: boolean regular?: boolean wide?: boolean }',
+ defaultValue: 'false',
+ description: 'Whether the content is hidden.',
+ required: false,
+ },
+ ],
+ displayName: 'TrailingAction',
+ },
+ {
+ name: 'PageHeader.Actions',
+ props: [
+ {name: 'className', type: 'string | undefined', description: 'CSS string', required: false},
+ {
+ name: 'hidden',
+ type: '| boolean | { narrow?: boolean regular?: boolean wide?: boolean }',
+ defaultValue: 'false',
+ description: 'Whether the content is hidden.',
+ required: false,
+ },
+ ],
+ displayName: 'Actions',
+ },
+ {
+ name: 'PageHeader.Breadcrumbs',
+ props: [
+ {name: 'className', type: 'string | undefined', description: 'CSS string', required: false},
+ {
+ name: 'hidden',
+ type: '| boolean | { narrow?: boolean regular?: boolean wide?: boolean }',
+ defaultValue: 'false',
+ description: 'Whether the content is hidden.',
+ required: false,
+ },
+ ],
+ displayName: 'Breadcrumbs',
+ },
+ {
+ name: 'PageHeader.Description',
+ props: [
+ {name: 'className', type: 'string | undefined', description: 'CSS string', required: false},
+ {
+ name: 'hidden',
+ type: '| boolean | { narrow?: boolean regular?: boolean wide?: boolean }',
+ defaultValue: 'false',
+ description: 'Whether the content is hidden.',
+ required: false,
+ },
+ ],
+ displayName: 'Description',
+ },
+ {
+ name: 'PageHeader.Navigation',
+ props: [
+ {
+ name: 'aria-label',
+ type: 'string',
+ description: 'The aria-label attribute for the navigaton component when it is rendered as a "nav" element.',
+ required: false,
+ },
+ {
+ name: 'aria-labelledby',
+ type: 'string',
+ description:
+ 'The aria-labelledby attribute for the navigaton component when it is rendered as a "nav" element.',
+ required: false,
+ },
+ {
+ name: 'as',
+ type: 'div | nav',
+ defaultValue: '"div"',
+ description: 'The HTML element used to render the navigation.',
+ required: false,
+ },
+ {name: 'className', type: 'string | undefined', description: 'CSS string', required: false},
+ {
+ name: 'hidden',
+ type: '| boolean | { narrow?: boolean regular?: boolean wide?: boolean }',
+ defaultValue: 'false',
+ description: 'Whether the content is hidden.',
+ required: false,
+ },
+ ],
+ displayName: 'Navigation',
+ },
+ ],
+})
diff --git a/packages/react/src/PageLayout/DragHandle.docs.ts b/packages/react/src/PageLayout/DragHandle.docs.ts
new file mode 100644
index 00000000000..4a413c1cee6
--- /dev/null
+++ b/packages/react/src/PageLayout/DragHandle.docs.ts
@@ -0,0 +1,101 @@
+import {defineComponent} from '../docs/component'
+
+export default defineComponent({
+ id: 'drag_handle',
+ name: 'DragHandle',
+ status: 'stable',
+ a11yReviewed: false,
+ importPath: '@primer/react',
+ stories: ['components-pagelayout-dev--standalone-resize'],
+ props: [
+ {
+ name: 'handleRef',
+ type: 'React.RefObject
',
+ description: 'Ref to the slider element for updating its ARIA values during drag.',
+ required: true,
+ },
+ {
+ name: 'onDragStart',
+ type: '(clientX: number) => void',
+ description: 'Called when a pointer drag starts, with the initial horizontal pointer position.',
+ required: true,
+ },
+ {
+ name: 'onDrag',
+ type: '(value: number, isKeyboard: boolean) => void',
+ description:
+ 'Update the pane width in this callback. Pointer drags report the horizontal pointer position. Arrow keys report a signed change of three pixels.',
+ required: true,
+ },
+ {
+ name: 'onDragEnd',
+ type: '() => void',
+ description: 'Called when the pointer loses capture or an arrow key is released.',
+ required: true,
+ },
+ {
+ name: 'onDoubleClick',
+ type: 'React.MouseEventHandler',
+ description: 'Handle a double-click on the slider, for example to reset the pane width.',
+ required: false,
+ },
+ {
+ name: 'aria-label',
+ type: 'string',
+ description: 'Accessible name for the slider. Ignored when `aria-labelledby` is provided.',
+ required: false,
+ defaultValue: "'Draggable pane splitter'",
+ },
+ {
+ name: 'aria-labelledby',
+ type: 'string',
+ description: 'ID of an element that names the slider. Takes precedence over `aria-label`.',
+ required: false,
+ },
+ {
+ name: 'aria-valuemin',
+ type: 'number',
+ description: 'Minimum value of the slider.',
+ required: false,
+ },
+ {
+ name: 'aria-valuemax',
+ type: 'number',
+ description: 'Maximum value of the slider.',
+ required: false,
+ },
+ {
+ name: 'aria-valuenow',
+ type: 'number',
+ description: 'Current value of the slider.',
+ required: false,
+ },
+ {
+ name: 'dragTargetRef',
+ type: 'React.RefObject',
+ description: 'Ref to the pane or other element that receives temporary styles while dragging.',
+ required: false,
+ },
+ {
+ name: 'contentWrapperRef',
+ type: 'React.RefObject',
+ description: 'Ref to a content wrapper that receives temporary CSS containment while dragging.',
+ required: false,
+ },
+ {
+ name: 'formatValueText',
+ type: '(valueNow: number) => string',
+ description: 'Formats the current width for `aria-valuetext`.',
+ required: false,
+ defaultValue: 'valueNow => `Pane width ${valueNow} pixels`',
+ },
+ {
+ name: 'data-component',
+ type: 'string',
+ description: 'Value for the `data-component` attribute.',
+ required: false,
+ defaultValue: "'PageLayout.DragHandle'",
+ },
+ ],
+ subcomponents: [],
+})
diff --git a/packages/react/src/PageLayout/PageLayout.docs.ts b/packages/react/src/PageLayout/PageLayout.docs.ts
new file mode 100644
index 00000000000..f68c51286fb
--- /dev/null
+++ b/packages/react/src/PageLayout/PageLayout.docs.ts
@@ -0,0 +1,433 @@
+import {defineComponent} from '../docs/component'
+
+export default defineComponent({
+ id: 'page_layout',
+ name: 'PageLayout',
+ status: 'alpha',
+ a11yReviewed: '2025-01-08',
+ stories: [
+ 'components-pagelayout--default',
+ 'components-pagelayout-features--pull-request-page',
+ 'components-pagelayout-features--sticky-pane',
+ 'components-pagelayout-features--nested-scroll-container',
+ 'components-pagelayout-features--custom-sticky-header',
+ 'components-pagelayout-features--resizable-pane',
+ 'components-pagelayout-features--scroll-container-within-page-layout-pane',
+ 'components-pagelayout-features--custom-pane-widths',
+ 'components-pagelayout-features--with-custom-pane-heading',
+ 'components-pagelayout-features--resizable-pane-without-persistence',
+ 'components-pagelayout-features--resizable-pane-with-custom-persistence',
+ 'components-pagelayout-features--resizable-pane-with-number-width',
+ 'components-pagelayout-features--resizable-pane-with-controlled-width',
+ 'components-pagelayout-features--sidebar-start',
+ 'components-pagelayout-features--sidebar-end',
+ 'components-pagelayout-features--resizable-sidebar',
+ 'components-pagelayout-features--resizable-sidebar-without-persistence',
+ 'components-pagelayout-features--resizable-sidebar-with-custom-persistence',
+ 'components-pagelayout-features--sidebar-with-pane-resizable',
+ 'components-pagelayout-features--sticky-sidebar',
+ 'components-pagelayout-features--sidebar-fullscreen-responsive-variant',
+ ],
+ importPath: '@primer/react',
+ props: [
+ {
+ name: 'containerWidth',
+ type: "| 'full' | 'medium' | 'large' | 'xlarge'",
+ defaultValue: "'xlarge'",
+ description: 'The maximum width of the page container.',
+ required: false,
+ },
+ {
+ name: 'padding',
+ type: "| 'none' | 'condensed' | 'normal'",
+ defaultValue: "'normal'",
+ description: 'The spacing between the outer edges of the page container and the viewport',
+ required: false,
+ },
+ {
+ name: 'columnGap',
+ type: "| 'none' | 'condensed' | 'normal'",
+ defaultValue: "'normal'",
+ description: '',
+ required: false,
+ },
+ {
+ name: 'rowGap',
+ type: "| 'none' | 'condensed' | 'normal'",
+ defaultValue: "'normal'",
+ description: '',
+ required: false,
+ },
+ ],
+ subcomponents: [
+ {
+ name: 'PageLayout.Header',
+ props: [
+ {
+ name: 'aria-label',
+ type: 'string | undefined',
+ description: 'A unique label for the rendered banner landmark',
+ required: false,
+ },
+ {
+ name: 'aria-labelledby',
+ type: 'string | undefined',
+ description: 'An id to an element which uniquely labels the rendered banner landmark',
+ required: false,
+ },
+ {
+ name: 'padding',
+ type: "| 'none' | 'condensed' | 'normal'",
+ defaultValue: "'none'",
+ description: 'The amount of padding inside the header.',
+ required: false,
+ },
+ {
+ name: 'divider',
+ type: "| 'none' | 'line' | { narrow?: | 'none' | 'line' | 'filled' regular?: | 'none' | 'line' wide?: | 'none' | 'line' }",
+ defaultValue: "'none'",
+ description: '',
+ required: false,
+ },
+ {
+ name: 'dividerWhenNarrow',
+ type: "| 'inherit' | 'none' | 'line' | 'filled'",
+ defaultValue: "'inherit'",
+ deprecated: true,
+ description: 'Use the divider prop with a responsive value instead.',
+ required: false,
+ },
+ {
+ name: 'hidden',
+ type: '| boolean | { narrow?: boolean regular?: boolean wide?: boolean }',
+ defaultValue: 'false',
+ description: 'Whether the header is hidden.',
+ required: false,
+ },
+ ],
+ displayName: 'Header',
+ },
+ {
+ name: 'PageLayout.Content',
+ props: [
+ {
+ name: 'aria-label',
+ type: 'string',
+ description: 'A unique label for the rendered main landmark',
+ required: false,
+ },
+ {
+ name: 'aria-labelledby',
+ type: 'string',
+ description: 'An id to an element which uniquely labels the rendered main landmark',
+ required: false,
+ },
+ {
+ name: 'as',
+ type: 'React.ElementType',
+ defaultValue: "'main'",
+ description: 'Change the root node to another HTML element or custom component.',
+ required: false,
+ },
+ {
+ name: 'width',
+ type: "| 'full' | 'medium' | 'large' | 'xlarge'",
+ defaultValue: "'full'",
+ description: 'The maximum width of the content region.',
+ required: false,
+ },
+ {
+ name: 'padding',
+ type: "| 'none' | 'condensed' | 'normal'",
+ defaultValue: "'none'",
+ description: 'The amount of padding inside the content.',
+ required: false,
+ },
+ {
+ name: 'hidden',
+ type: '| boolean | { narrow?: boolean regular?: boolean wide?: boolean }',
+ defaultValue: 'false',
+ description: 'Whether the content is hidden.',
+ required: false,
+ },
+ ],
+ displayName: 'Content',
+ },
+ {
+ name: 'PageLayout.Pane',
+ props: [
+ {
+ name: 'aria-label',
+ type: 'string | undefined',
+ description: "Label for the pane. Required if the pane overflows and doesn't have aria-labelledby.",
+ required: false,
+ },
+ {
+ name: 'aria-labelledby',
+ type: 'string | undefined',
+ description:
+ "Id of an element that acts as a label for the pane. Required if the pane overflows and doesn't have aria-label.",
+ required: false,
+ },
+ {
+ name: 'width',
+ type: "| 'small' | 'medium' | 'large' | { min: string max: string default: string }",
+ defaultValue: "'medium'",
+ description:
+ "The width of the pane. If using custom widths, provide an object with keys 'min', 'max' and 'default'.",
+ required: false,
+ },
+ {
+ name: 'minWidth',
+ type: 'number',
+ defaultValue: '256',
+ description: 'The minimum width of the pane.',
+ required: false,
+ },
+ {
+ name: 'resizable',
+ type: 'boolean',
+ defaultValue: 'false',
+ description:
+ 'When true, the pane may be resized by the user. Uses localStorage persistence by default. Note: with default persistence in SSR, the server-rendered width may differ from the stored client width, causing a brief layout shift on hydration. Use `onResizeEnd` with server-aware storage to avoid this.',
+ required: false,
+ },
+ {
+ name: 'currentWidth',
+ type: 'number | undefined',
+ description:
+ 'Current/controlled width value in pixels. Required when `onResizeEnd` is provided. Pass `undefined` when the persisted value has not loaded yet. The `width` prop still defines the default used when resetting (e.g., double-click).',
+ required: false,
+ },
+ {
+ name: 'onResizeEnd',
+ type: '(width: number) => void',
+ description:
+ 'Callback fired when a resize operation ends (drag release or keyboard key up). When provided, replaces localStorage persistence. Requires `currentWidth`.',
+ required: false,
+ },
+ {
+ name: 'widthStorageKey',
+ type: 'string',
+ defaultValue: "'paneWidth'",
+ description:
+ 'localStorage key used to persist the pane width across sessions. Only applies when `resizable` is `true` and no `onResizeEnd` callback is provided.',
+ required: false,
+ },
+ {
+ name: 'sticky',
+ type: 'boolean',
+ defaultValue: 'false',
+ description: 'Whether the pane should stick to the top of the screen while the content scrolls.',
+ required: false,
+ },
+ {
+ name: 'offsetHeader',
+ type: 'number | string',
+ defaultValue: '0',
+ description:
+ 'Use offsetHeader along with the sticky prop to push the sticky pane down to make room for a sticky header if necessary. Use the type `string` to specify the height with a unit i.e. 5rem; otherwise the type `number` will be taken as px.',
+ required: false,
+ },
+ {
+ name: 'padding',
+ type: "| 'none' | 'condensed' | 'normal'",
+ defaultValue: "'none'",
+ description: 'The amount of padding inside the pane.',
+ required: false,
+ },
+ {
+ name: 'divider',
+ type: "| 'none' | 'line' | { narrow?: | 'none' | 'line' | 'filled' regular?: | 'none' | 'line' wide?: | 'none' | 'line' }",
+ defaultValue: "'none'",
+ description: '',
+ required: false,
+ },
+ {
+ name: 'dividerWhenNarrow',
+ type: "| 'inherit' | 'none' | 'line' | 'filled'",
+ defaultValue: "'inherit'",
+ deprecated: true,
+ description: 'Use the divider prop with a responsive value instead.',
+ required: false,
+ },
+ {
+ name: 'hidden',
+ type: '| boolean | { narrow?: boolean regular?: boolean wide?: boolean }',
+ defaultValue: 'false',
+ description: 'Whether the pane is hidden.',
+ required: false,
+ },
+ {
+ name: 'position',
+ type: "'end' | 'start' | { narrow?: 'end' | 'start'; regular?: 'end' | 'start'; wide?: 'end' | 'start'; }",
+ description: 'Which side of the page the pane should be on. Can be changed for different viewport widths.',
+ defaultValue: '',
+ required: false,
+ },
+ {
+ name: 'ref',
+ type: 'React.RefObject',
+ required: false,
+ description:
+ 'Allows getting a ref to the component instance.\nOnce the component unmounts, React will set `ref.current` to `null`\n(or call the ref with `null` if you passed a callback ref).',
+ },
+ ],
+ displayName: 'Pane',
+ },
+ {
+ name: 'PageLayout.Sidebar',
+ props: [
+ {
+ name: 'aria-label',
+ type: 'string | undefined',
+ description: 'A unique label for the sidebar region.',
+ required: false,
+ },
+ {
+ name: 'aria-labelledby',
+ type: 'string | undefined',
+ description: 'An id to an element which uniquely labels the sidebar region.',
+ required: false,
+ },
+ {
+ name: 'position',
+ type: "'start' | 'end'",
+ defaultValue: "'start'",
+ description:
+ 'Position of the sidebar relative to the page layout. The sidebar spans the full height of the layout, adjacent to the header, content, and footer.',
+ required: false,
+ },
+ {
+ name: 'width',
+ type: "| 'small' | 'medium' | 'large' | { min: string max: string default: string }",
+ defaultValue: "'medium'",
+ description:
+ "The width of the sidebar. If using custom widths, provide an object with keys 'min', 'max' and 'default'.",
+ required: false,
+ },
+ {
+ name: 'minWidth',
+ type: 'number',
+ defaultValue: '256',
+ description: 'Minimum width of the sidebar when resizable.',
+ required: false,
+ },
+ {
+ name: 'resizable',
+ type: 'boolean',
+ defaultValue: 'false',
+ description:
+ 'When true, the sidebar may be resized by the user. By default no persistence is applied; pass `widthStorageKey` to persist via localStorage, or use `onResizeEnd` + `currentWidth` for fully controlled persistence.',
+ required: false,
+ },
+ {
+ name: 'currentWidth',
+ type: 'number | undefined',
+ description:
+ 'Current/controlled width value in pixels. Required when `onResizeEnd` is provided. Pass `undefined` when the persisted value has not loaded yet. The `width` prop still defines the default used when resetting (e.g., double-click).',
+ required: false,
+ },
+ {
+ name: 'onResizeEnd',
+ type: '(width: number) => void',
+ description:
+ 'Callback fired when a resize operation ends (drag release or keyboard key up). When provided, replaces localStorage persistence. Requires `currentWidth`.',
+ required: false,
+ },
+ {
+ name: 'widthStorageKey',
+ type: 'string',
+ description:
+ 'localStorage key used to persist the sidebar width across sessions. Only applies when `resizable` is `true` and no `onResizeEnd` callback is provided. When omitted, localStorage is not used.',
+ required: false,
+ },
+ {
+ name: 'padding',
+ type: "| 'none' | 'condensed' | 'normal'",
+ defaultValue: "'none'",
+ description: 'The amount of padding inside the sidebar.',
+ required: false,
+ },
+ {
+ name: 'divider',
+ type: "| 'none' | 'line'",
+ defaultValue: "'none'",
+ description: 'Divider style between the sidebar and the rest of the layout.',
+ required: false,
+ },
+ {
+ name: 'sticky',
+ type: 'boolean',
+ defaultValue: 'false',
+ description:
+ 'Whether the sidebar sticks to the viewport when scrolling. When enabled, the sidebar uses position: sticky with top: 0 and height: 100vh.',
+ required: false,
+ },
+ {
+ name: 'responsiveVariant',
+ type: "| 'default' | 'fullscreen'",
+ defaultValue: "'default'",
+ description:
+ "Controls sidebar behavior at narrow viewport widths (below 768px). 'default' retains its normal inline layout. 'fullscreen' expands to cover the full viewport like a dialog overlay.",
+ required: false,
+ },
+ {
+ name: 'hidden',
+ type: '| boolean | { narrow?: boolean regular?: boolean wide?: boolean }',
+ defaultValue: 'false',
+ description: 'Whether the sidebar is hidden.',
+ required: false,
+ },
+ ],
+ displayName: 'Sidebar',
+ },
+ {
+ name: 'PageLayout.Footer',
+ props: [
+ {
+ name: 'aria-label',
+ type: 'string | undefined',
+ description: 'A unique label for the rendered contentinfo landmark',
+ required: false,
+ },
+ {
+ name: 'aria-labelledby',
+ type: 'string | undefined',
+ description: 'An id to an element which uniquely labels the rendered contentinfo landmark',
+ required: false,
+ },
+ {
+ name: 'padding',
+ type: "| 'none' | 'condensed' | 'normal'",
+ defaultValue: "'none'",
+ description: 'The amount of padding inside the footer.',
+ required: false,
+ },
+ {
+ name: 'divider',
+ type: "| 'none' | 'line' | { narrow?: | 'none' | 'line' | 'filled' regular?: | 'none' | 'line' wide?: | 'none' | 'line' }",
+ defaultValue: "'none'",
+ description: '',
+ required: false,
+ },
+ {
+ name: 'dividerWhenNarrow',
+ type: "| 'inherit' | 'none' | 'line' | 'filled'",
+ defaultValue: "'inherit'",
+ deprecated: true,
+ description: 'Use the divider prop with a responsive value instead.',
+ required: false,
+ },
+ {
+ name: 'hidden',
+ type: '| boolean | { narrow?: boolean regular?: boolean wide?: boolean }',
+ defaultValue: 'false',
+ description: 'Whether the footer is hidden.',
+ required: false,
+ },
+ ],
+ displayName: 'Footer',
+ },
+ ],
+})
diff --git a/packages/react/src/Pagehead/Pagehead.docs.ts b/packages/react/src/Pagehead/Pagehead.docs.ts
new file mode 100644
index 00000000000..d107606450c
--- /dev/null
+++ b/packages/react/src/Pagehead/Pagehead.docs.ts
@@ -0,0 +1,20 @@
+import {defineComponent} from '../docs/component'
+
+export default defineComponent({
+ id: 'pagehead',
+ name: 'Pagehead',
+ status: 'deprecated',
+ a11yReviewed: false,
+ stories: [],
+ importPath: '@primer/react/deprecated',
+ props: [
+ {
+ name: 'as',
+ type: 'string',
+ defaultValue: 'div',
+ description: 'Sets the underlying HTML tag for the component',
+ required: false,
+ },
+ ],
+ subcomponents: [],
+})
diff --git a/packages/react/src/Pagination/Pagination.docs.ts b/packages/react/src/Pagination/Pagination.docs.ts
new file mode 100644
index 00000000000..f73c73d857d
--- /dev/null
+++ b/packages/react/src/Pagination/Pagination.docs.ts
@@ -0,0 +1,68 @@
+import {defineComponent} from '../docs/component'
+
+export default defineComponent({
+ id: 'pagination',
+ name: 'Pagination',
+ status: 'alpha',
+ a11yReviewed: '2025-01-08',
+ stories: [
+ 'components-pagination--default',
+ 'components-pagination-features--larger-page-count-margin',
+ 'components-pagination-features--hide-page-numbers',
+ 'components-pagination-features--hide-page-numbers-by-viewport',
+ 'components-pagination-features--higher-surrounding-page-count',
+ ],
+ importPath: '@primer/react',
+ props: [
+ {
+ name: 'currentPage',
+ type: 'number',
+ required: true,
+ description: 'The currently selected page.',
+ },
+ {name: 'pageCount', type: 'number', required: true, description: 'The total number of pages.'},
+ {
+ name: 'hrefBuilder',
+ type: 'function',
+ defaultValue: '',
+ description: 'A function to generate links based on page number.',
+ required: false,
+ },
+ {
+ name: 'marginPageCount',
+ type: 'number',
+ defaultValue: '1',
+ description: 'How many pages to always show at the left and right of the component.',
+ required: false,
+ },
+ {
+ name: 'onPageChange',
+ type: 'function',
+ defaultValue: '(e: MouseEvent, n: number) => void',
+ description: 'Called with event and page number when a page is clicked.',
+ required: false,
+ },
+ {
+ name: 'showPages',
+ type: 'boolean | { narrow?: boolean, regular?: boolean, wide?: boolean }',
+ defaultValue: 'true',
+ description: 'Whether or not to show the individual page links.',
+ required: false,
+ },
+ {
+ name: 'surroundingPageCount',
+ type: 'number',
+ defaultValue: '2',
+ description: 'How many pages to display on each side of the currently selected page.',
+ required: false,
+ },
+ {
+ name: 'renderPage',
+ type: 'function',
+ defaultValue: '(props: PageProps) => ReactNode',
+ description: 'Provide a custom component or render prop to render each page link within the component.',
+ required: false,
+ },
+ ],
+ subcomponents: [],
+})
diff --git a/packages/react/src/Popover/Popover.docs.ts b/packages/react/src/Popover/Popover.docs.ts
new file mode 100644
index 00000000000..1555397e66e
--- /dev/null
+++ b/packages/react/src/Popover/Popover.docs.ts
@@ -0,0 +1,94 @@
+import {defineComponent} from '../docs/component'
+
+export default defineComponent({
+ id: 'popover',
+ name: 'Popover',
+ status: 'alpha',
+ a11yReviewed: '2025-01-08',
+ stories: ['components-popover--default'],
+ importPath: '@primer/react',
+ props: [
+ {
+ name: 'as',
+ type: 'string',
+ defaultValue: 'div',
+ description: 'Sets the underlying HTML tag for the component',
+ required: false,
+ },
+ {
+ name: 'caret',
+ type: "| 'top' | 'bottom' | 'left' | 'right' | 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right' | 'left-bottom' | 'left-top' | 'right-bottom' | 'right-top' ",
+ defaultValue: "'top'",
+ description: 'Controls the position of the caret',
+ required: false,
+ },
+ {
+ name: 'open',
+ type: 'boolean',
+ defaultValue: 'false',
+ description: 'Controls the visibility of the popover.',
+ required: false,
+ },
+ {
+ name: 'relative',
+ type: 'boolean',
+ defaultValue: 'false',
+ description: 'Set to true to render the popover using relative positioning.',
+ required: false,
+ },
+ ],
+ subcomponents: [
+ {
+ name: 'Popover.Content',
+ props: [
+ {
+ name: 'as',
+ type: 'string',
+ defaultValue: 'div',
+ description: 'Sets the underlying HTML tag for the component',
+ required: false,
+ },
+ {
+ name: 'width',
+ type: "| 'xsmall' | 'small' | 'medium' | 'large' | 'xlarge' | 'auto'",
+ defaultValue: "'small'",
+ description: 'Sets the width of the popover content.',
+ required: false,
+ },
+ {
+ name: 'height',
+ type: "| 'small' | 'medium' | 'large' | 'xlarge' | 'fit-content' | 'auto'",
+ defaultValue: "'fit-content'",
+ description: 'Sets the height of the popover content.',
+ required: false,
+ },
+ {
+ name: 'overflow',
+ type: "| 'auto' | 'hidden' | 'scroll' | 'visible'",
+ defaultValue: "'auto'",
+ description: 'Sets the overflow behavior of the popover content.',
+ required: false,
+ },
+ {
+ name: 'onClickOutside',
+ type: '(event: MouseEvent | TouchEvent) => void',
+ description: 'Callback fired when a click is detected outside the popover content',
+ required: false,
+ },
+ {
+ name: 'onEscape',
+ type: '(event: KeyboardEvent) => void',
+ description: 'Callback fired when the Escape key is pressed while the popover is open',
+ required: false,
+ },
+ {
+ name: 'ignoreClickRefs',
+ type: 'Array>',
+ description: 'Refs to elements that should be ignored when detecting outside clicks',
+ required: false,
+ },
+ ],
+ displayName: 'Content',
+ },
+ ],
+})
diff --git a/packages/react/src/Portal/Portal.docs.ts b/packages/react/src/Portal/Portal.docs.ts
new file mode 100644
index 00000000000..09a376d8700
--- /dev/null
+++ b/packages/react/src/Portal/Portal.docs.ts
@@ -0,0 +1,32 @@
+import {defineComponent} from '../docs/component'
+
+export default defineComponent({
+ id: 'portal',
+ name: 'Portal',
+ status: 'alpha',
+ a11yReviewed: false,
+ stories: [
+ 'behaviors-portal--default',
+ 'behaviors-portal-features--custom-portal-root-by-id',
+ 'behaviors-portal-features--custom-portal-root-by-registration',
+ 'behaviors-portal-features--multiple-portal-roots',
+ ],
+ importPath: '@primer/react',
+ props: [
+ {
+ name: 'onMount',
+ type: 'function',
+ description: 'Called when this portal is added to the DOM',
+ required: false,
+ },
+ {
+ name: 'containerName',
+ type: 'string',
+ defaultValue: '',
+ description:
+ 'Renders the portal children into the container registered with the given name. If omitted, children are rendered into the default portal root.',
+ required: false,
+ },
+ ],
+ subcomponents: [],
+})
diff --git a/packages/react/src/ProgressBar/ProgressBar.docs.ts b/packages/react/src/ProgressBar/ProgressBar.docs.ts
new file mode 100644
index 00000000000..ae8b14cb8ff
--- /dev/null
+++ b/packages/react/src/ProgressBar/ProgressBar.docs.ts
@@ -0,0 +1,85 @@
+import {defineComponent} from '../docs/component'
+
+export default defineComponent({
+ id: 'progress_bar',
+ name: 'ProgressBar',
+ status: 'alpha',
+ a11yReviewed: '2025-01-08',
+ stories: [
+ 'components-progressbar--default',
+ 'components-progressbar-features--progress-zero',
+ 'components-progressbar-features--progress-half',
+ 'components-progressbar-features--progress-done',
+ 'components-progressbar-features--size-small',
+ 'components-progressbar-features--size-large',
+ 'components-progressbar-features--inline',
+ 'components-progressbar-features--all-colors',
+ 'components-progressbar-features--multiple-items',
+ 'components-progressbar-features--animated',
+ ],
+ importPath: '@primer/react',
+ props: [
+ {
+ name: 'animated',
+ type: 'boolean',
+ description: 'Whether the filled in area(s) of the progress bar will be animated or not',
+ required: false,
+ },
+ {
+ name: 'progress',
+ type: 'number',
+ defaultValue: '0',
+ description: 'Used to set the size of the green bar',
+ required: false,
+ },
+ {
+ name: 'barSize',
+ type: "| 'small' | 'large' | 'default'",
+ defaultValue: "'default'",
+ description: 'Controls the height of the progress bar. If omitted, height is set to the default height.',
+ required: false,
+ },
+ {
+ name: 'inline',
+ type: 'boolean',
+ defaultValue: 'false',
+ description: 'Styles the progress bar inline',
+ required: false,
+ },
+ {
+ name: 'bg',
+ type: 'string',
+ defaultValue: "'bg.successInverse'",
+ description: 'Set the progress bar color',
+ required: false,
+ },
+ ],
+ subcomponents: [
+ {
+ name: 'ProgressBar.Item',
+ props: [
+ {
+ name: 'aria-label',
+ type: 'string',
+ description: 'Defines a string value that labels the current element.\n@see aria-labelledby.',
+ required: false,
+ },
+ {
+ name: 'bg',
+ type: 'string',
+ description: 'Set the progress segment color',
+ defaultValue: 'success.emphasis',
+ required: false,
+ },
+ {
+ name: 'progress',
+ type: 'string | number',
+ description: 'Used to set the size of the green bar',
+ defaultValue: '0',
+ required: false,
+ },
+ ],
+ displayName: 'Item',
+ },
+ ],
+})
diff --git a/packages/react/src/Radio/Radio.docs.ts b/packages/react/src/Radio/Radio.docs.ts
new file mode 100644
index 00000000000..207c99cba3b
--- /dev/null
+++ b/packages/react/src/Radio/Radio.docs.ts
@@ -0,0 +1,61 @@
+import {defineComponent} from '../docs/component'
+
+export default defineComponent({
+ id: 'radio',
+ name: 'Radio',
+ status: 'alpha',
+ a11yReviewed: '2025-01-08',
+ stories: [
+ 'components-radio--default',
+ 'components-radio-features--with-leading-visual',
+ 'components-radio-features--disabled',
+ 'components-radio-features--with-caption',
+ ],
+ importPath: '@primer/react',
+ props: [
+ {
+ name: 'value',
+ type: 'string',
+ required: true,
+ description: 'A unique value that is never shown to the user',
+ },
+ {
+ name: 'name',
+ type: 'string',
+ description: 'Required for grouping multiple radios',
+ required: false,
+ },
+ {
+ name: 'checked',
+ type: 'boolean',
+ description: 'Modifies true/false value of the native radio',
+ required: false,
+ },
+ {
+ name: 'defaultChecked',
+ type: 'boolean',
+ description: 'Selects the radio by default in uncontrolled mode',
+ required: false,
+ },
+ {
+ name: 'onChange',
+ type: '(event: React.ChangeEvent) => void',
+ description: 'A callback function that is triggered when the input state has been changed',
+ required: false,
+ },
+ {
+ name: 'disabled',
+ type: 'boolean',
+ description: 'Modifies the native disabled state of the native checkbox',
+ required: false,
+ },
+ {
+ name: 'ref',
+ type: 'React.RefObject',
+ required: false,
+ description:
+ 'Allows getting a ref to the component instance.\nOnce the component unmounts, React will set `ref.current` to `null`\n(or call the ref with `null` if you passed a callback ref).',
+ },
+ ],
+ subcomponents: [],
+})
diff --git a/packages/react/src/RadioGroup/RadioGroup.docs.ts b/packages/react/src/RadioGroup/RadioGroup.docs.ts
new file mode 100644
index 00000000000..6f431c9c4fd
--- /dev/null
+++ b/packages/react/src/RadioGroup/RadioGroup.docs.ts
@@ -0,0 +1,110 @@
+import {defineComponent} from '../docs/component'
+
+export default defineComponent({
+ id: 'radio_group',
+ name: 'RadioGroup',
+ status: 'alpha',
+ a11yReviewed: '2025-01-08',
+ stories: [
+ 'components-radiogroup--default',
+ 'components-radiogroup-features--visually-hidden-label',
+ 'components-radiogroup-features--with-external-label',
+ 'components-radiogroup-features--error',
+ 'components-radiogroup-features--success',
+ 'components-radiogroup-features--caption',
+ ],
+ importPath: '@primer/react',
+ props: [
+ {
+ name: 'aria-labelledby',
+ type: 'string',
+ description: 'Used when associating the input group with a label other than RadioGroup.Label',
+ required: false,
+ },
+ {
+ name: 'children',
+ type: 'RadioGroup.Label | RadioGroup.Caption | RadioGroup.Validation | FormControl',
+ required: true,
+ description: '',
+ },
+ {
+ name: 'disabled',
+ type: 'boolean',
+ defaultValue: 'false',
+ description: 'Whether the input group allows user input',
+ required: false,
+ },
+ {
+ name: 'id',
+ type: 'string',
+ defaultValue: 'A generated string',
+ description:
+ 'The unique identifier for this input group. Used to associate the label, validation text, and caption text.\nYou may want a custom ID to make it easier to select elements in integration tests.',
+ required: false,
+ },
+ {
+ name: 'name',
+ type: 'string',
+ required: true,
+ description: 'The name used to identify this group of radios',
+ },
+ {
+ name: 'onChange',
+ type: '(selected: string | null, e?: ChangeEvent) => void',
+ description: 'An onChange handler that gets called when the selection changes',
+ required: false,
+ },
+ {
+ name: 'required',
+ type: 'boolean',
+ defaultValue: 'false',
+ description: 'If true, the user must make a selection before the owning form can be submitted',
+ required: false,
+ },
+ ],
+ subcomponents: [
+ {
+ name: 'RadioGroup.Label',
+ props: [
+ {
+ name: 'visuallyHidden',
+ type: 'boolean',
+ defaultValue: 'false',
+ description: 'If true, the fieldset legend will be visually hidden',
+ required: false,
+ },
+ ],
+ displayName: 'Label',
+ },
+ {
+ name: 'RadioGroup.Caption',
+ props: [
+ {
+ name: 'children',
+ type: 'React.ReactNode',
+ description: 'The caption content',
+ required: false,
+ },
+ ],
+ displayName: 'Caption',
+ },
+ {
+ name: 'RadioGroup.Validation',
+ props: [
+ {
+ name: 'children',
+ type: 'React.ReactNode',
+ description: 'The validation message',
+ required: false,
+ },
+ {
+ name: 'variant',
+ type: "'error' | 'success'",
+ required: true,
+ description: 'Changes the visual style to match the validation status',
+ },
+ ],
+ displayName: 'Validation',
+ },
+ ],
+})
diff --git a/packages/react/src/RelativeTime/RelativeTime.docs.ts b/packages/react/src/RelativeTime/RelativeTime.docs.ts
new file mode 100644
index 00000000000..852bdf2000f
--- /dev/null
+++ b/packages/react/src/RelativeTime/RelativeTime.docs.ts
@@ -0,0 +1,149 @@
+import {defineComponent} from '../docs/component'
+
+export default defineComponent({
+ id: 'relative_time',
+ name: 'RelativeTime',
+ status: 'alpha',
+ a11yReviewed: '2025-01-08',
+ stories: [
+ 'components-relativetime--default',
+ 'components-relativetime-features--micro-format',
+ 'components-relativetime-features--recent-time',
+ 'components-relativetime-features--count-down-timer',
+ ],
+ importPath: '@primer/react',
+ props: [
+ {
+ name: 'datetime',
+ type: 'string',
+ defaultValue: '',
+ required: true,
+ description: 'An ISO8601 time representing the time',
+ },
+ {
+ name: 'date',
+ type: 'string',
+ defaultValue: '',
+ description:
+ 'Instead of passing the `datetime`, it is possible to pass a full `Date` object into the `date` prop',
+ required: false,
+ },
+ {
+ name: 'format',
+ type: "'auto' | 'micro' | 'elapsed'",
+ defaultValue: "'auto'",
+ description: 'The format with which to display the time',
+ required: false,
+ },
+ {
+ name: 'tense',
+ type: "'auto' | 'past' | 'future'",
+ defaultValue: "'auto'",
+ description: 'The tense to use when displaying a relative time',
+ required: false,
+ },
+ {
+ name: 'precision',
+ type: "'year' | 'month' | 'day' | 'hour' | 'minute' | 'second'",
+ defaultValue: "'second'",
+ description: 'The precision to use when displaying an elapsed time',
+ required: false,
+ },
+ {
+ name: 'threshold',
+ type: 'string',
+ defaultValue: "'P30D'",
+ description: 'The threshold (ISO8601 duration) to display relative dates within',
+ required: false,
+ },
+ {
+ name: 'prefix',
+ type: 'string',
+ defaultValue: "'on'",
+ description: 'The prefix to use when displaying a localised (non relative) date',
+ required: false,
+ },
+ {
+ name: 'second',
+ type: "'numeric' | '2-digit'",
+ description: 'The format with which to render seconds',
+ required: false,
+ },
+ {
+ name: 'minute',
+ type: "'numeric' | '2-digit'",
+ description: 'The format with which to render minutes',
+ required: false,
+ },
+ {
+ name: 'hour',
+ type: "'numeric' | '2-digit'",
+ description: 'The format with which to render hours',
+ required: false,
+ },
+ {
+ name: 'weekday',
+ type: "'short' | 'long' | 'narrow'",
+ defaultValue: '',
+ description: 'The format with which to render weekdays',
+ required: false,
+ },
+ {
+ name: 'day',
+ type: "'numeric' | '2-digit'",
+ defaultValue: '',
+ description: 'The format with which to render days',
+ required: false,
+ },
+ {
+ name: 'month',
+ type: "'numeric' | '2-digit' | 'short' | 'long' | 'narrow'",
+ defaultValue: "'numeric'",
+ description: 'The format with which to render months',
+ required: false,
+ },
+ {
+ name: 'year',
+ type: "'numeric' | '2-digit'",
+ defaultValue: '',
+ description: 'The format with which to render years',
+ required: false,
+ },
+ {
+ name: 'timeZoneName',
+ type: "'long' | 'short' | 'shortOffset' | 'longOffset' | 'shortGeneric' | 'longGeneric'",
+ description: 'The format with which to render the time zone',
+ required: false,
+ },
+ {
+ name: 'ref',
+ type: 'React.RefObject',
+ description: 'Ref to the rendered `` element on React 19.',
+ required: false,
+ },
+ {
+ name: 'noTitle',
+ type: 'boolean',
+ defaultValue: '',
+ description: 'Removes the `title` attribute provided on the element by default',
+ required: false,
+ },
+ {
+ name: 'attributeChangedCallback',
+ type: '(attrName: string, oldValue: unknown, newValue: unknown) => void',
+ description: '',
+ defaultValue: '',
+ required: false,
+ },
+ {name: 'connectedCallback', type: '() => void', description: '', defaultValue: '', required: false},
+ {
+ name: 'onRelativeTimeUpdated',
+ type: 'null | (event: RelativeTimeUpdatedEvent) => void',
+ description: '',
+ defaultValue: '',
+ required: false,
+ },
+ {name: 'update', type: '() => void', description: '', defaultValue: '', required: false},
+ ],
+ subcomponents: [],
+})
diff --git a/packages/react/src/ScrollableRegion/ScrollableRegion.docs.ts b/packages/react/src/ScrollableRegion/ScrollableRegion.docs.ts
new file mode 100644
index 00000000000..34a18a5fcc3
--- /dev/null
+++ b/packages/react/src/ScrollableRegion/ScrollableRegion.docs.ts
@@ -0,0 +1,47 @@
+import {defineComponent} from '../docs/component'
+
+export default defineComponent({
+ id: 'scrollable_region',
+ name: 'ScrollableRegion',
+ status: 'draft',
+ a11yReviewed: false,
+ importPath: '@primer/react/experimental',
+ stories: [
+ 'experimental-components-scrollableregion--default',
+ 'experimental-components-scrollableregion--playground',
+ ],
+ props: [
+ {
+ name: 'aria-label',
+ type: 'string',
+ description:
+ 'Accessible name for the region when its content overflows. Provide either this prop or `aria-labelledby`, not both.',
+ required: false,
+ },
+ {
+ name: 'aria-labelledby',
+ type: 'string',
+ description:
+ 'ID of the element that names the region when its content overflows. Provide either this prop or `aria-label`, not both.',
+ required: false,
+ },
+ {
+ name: 'children',
+ type: 'React.ReactNode',
+ description:
+ 'Content to render inside the scrollable region. When it overflows, the region can receive keyboard focus.',
+ required: false,
+ },
+ {
+ name: 'className',
+ type: 'string',
+ description: 'Additional CSS class for the scrollable region.',
+ required: false,
+ },
+ ],
+ subcomponents: [],
+ passthrough: {
+ element: 'div',
+ url: 'https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/div',
+ },
+})
diff --git a/packages/react/src/SegmentedControl/SegmentedControl.docs.ts b/packages/react/src/SegmentedControl/SegmentedControl.docs.ts
new file mode 100644
index 00000000000..d6f05d798f8
--- /dev/null
+++ b/packages/react/src/SegmentedControl/SegmentedControl.docs.ts
@@ -0,0 +1,169 @@
+import {defineComponent} from '../docs/component'
+
+export default defineComponent({
+ id: 'segmented_control',
+ name: 'SegmentedControl',
+ status: 'alpha',
+ a11yReviewed: '2025-01-08',
+ stories: [
+ 'components-segmentedcontrol--default',
+ 'components-segmentedcontrol-features--with-icons',
+ 'components-segmentedcontrol-features--controlled',
+ 'components-segmentedcontrol-features--variant-narrow-hide-labels',
+ 'components-segmentedcontrol-features--variant-narrow-action-menu',
+ 'components-segmentedcontrol-features--variant-narrow-action-menu-with-action',
+ 'components-segmentedcontrol-features--fullwidth-narrow',
+ 'components-segmentedcontrol-features--fullwidth-regular',
+ 'components-segmentedcontrol-features--fullwidth-all',
+ 'components-segmentedcontrol-features--icon-only',
+ 'components-segmentedcontrol-features--associated-with-a-label-and-caption',
+ 'components-segmentedcontrol-features--variant-subtle',
+ ],
+ importPath: '@primer/react',
+ props: [
+ {name: 'aria-label', type: 'string', description: '', required: false},
+ {name: 'aria-labelledby', type: 'string', description: '', required: false},
+ {name: 'aria-describedby', type: 'string', description: '', required: false},
+ {
+ name: 'fullWidth',
+ type: '| boolean | { narrow?: boolean regular?: boolean wide?: boolean }',
+ description: 'Whether the control fills the width of its parent',
+ required: false,
+ },
+ {
+ name: 'onChange',
+ type: '(selectedIndex?: number) => void',
+ description: 'The handler that gets called when a segment is selected',
+ required: false,
+ },
+ {
+ name: 'variant',
+ type: "| 'default' | 'subtle' | { narrow?: 'hideLabels' | 'dropdown' | 'default' | 'subtle' regular?: 'hideLabels' | 'dropdown' | 'default' | 'subtle' wide?: 'hideLabels' | 'dropdown' | 'default' | 'subtle' }",
+ defaultValue: "'default'",
+ description: "Configure the control's visual treatment or responsive behavior in tight spaces.",
+ required: false,
+ },
+ {
+ name: 'size',
+ type: "'small' | 'medium'",
+ description: 'The size of the buttons',
+ defaultValue: '',
+ required: false,
+ },
+ ],
+ subcomponents: [
+ {
+ name: 'SegmentedControl.Button',
+ props: [
+ {
+ name: 'leadingVisual',
+ type: 'Component',
+ description: 'The leading visual comes before item label',
+ required: false,
+ },
+ {
+ name: 'leadingIcon',
+ deprecated: true,
+ type: 'Component',
+ description: 'Deprecated: use `leadingVisual` instead. The leading icon comes before item label.',
+ required: false,
+ },
+ {
+ name: 'selected',
+ type: 'boolean',
+ defaultValue: '',
+ description:
+ 'Whether the segment is selected. This is used for controlled SegmentedControls, and needs to be updated using the onChange handler on SegmentedControl.',
+ required: false,
+ },
+ {
+ name: 'defaultSelected',
+ type: 'boolean',
+ defaultValue: '',
+ description:
+ 'Whether the segment is selected. This is used for uncontrolled SegmentedControls to pick one SegmentedControlButton that is selected on the initial render.',
+ required: false,
+ },
+ {
+ name: 'count',
+ type: 'number | string',
+ description: 'The number to display in the counter label.',
+ required: false,
+ },
+ ],
+ displayName: 'Button',
+ },
+ {
+ name: 'SegmentedControl.IconButton',
+ props: [
+ {name: 'aria-label', type: 'string', required: true, description: ''},
+ {
+ name: 'icon',
+ type: 'Component',
+ required: true,
+ description: 'The icon that represents the segmented control item',
+ },
+ {
+ name: 'selected',
+ type: 'boolean',
+ defaultValue: '',
+ description:
+ 'Whether the segment is selected. This is used for controlled SegmentedControls, and needs to be updated using the onChange handler on SegmentedControl.',
+ required: false,
+ },
+ {
+ name: 'defaultSelected',
+ type: 'boolean',
+ defaultValue: '',
+ description:
+ 'Whether the segment is selected. This is used for uncontrolled SegmentedControls to pick one SegmentedControlButton that is selected on the initial render.',
+ required: false,
+ },
+ {
+ name: 'tooltipDirection',
+ type: "'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w' | 'nw'",
+ required: false,
+ description: 'The direction for the tooltip.',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ required: false,
+ description:
+ 'If `description` is provided, we will use a Tooltip to describe the button. Then `aria-label` is used to label the button.',
+ defaultValue: '',
+ },
+ ],
+ displayName: 'IconButton',
+ },
+ {
+ name: 'SegmentedControl.Divider',
+ props: [
+ {
+ name: 'className',
+ type: 'string',
+ required: false,
+ description: 'Additional CSS class names for the divider.',
+ },
+ {name: 'style', type: 'React.CSSProperties', required: false, description: 'Inline styles for the divider.'},
+ ],
+ displayName: 'Divider',
+ },
+ {
+ name: 'SegmentedControl.Action',
+ props: [
+ {name: 'label', type: 'string', required: true, description: 'Accessible label for the action icon button.'},
+ {name: 'icon', type: 'Component', required: true, description: 'The icon rendered by the action button.'},
+ {
+ name: 'onClick',
+ type: '() => void',
+ description: 'The handler that gets called when the action button is clicked.',
+ required: false,
+ },
+ {name: 'disabled', type: 'boolean', description: 'Whether the action is disabled.', required: false},
+ {name: 'loading', type: 'boolean', description: 'Whether the action is in a loading state.', required: false},
+ ],
+ displayName: 'Action',
+ },
+ ],
+})
diff --git a/packages/react/src/Select/Select.docs.ts b/packages/react/src/Select/Select.docs.ts
new file mode 100644
index 00000000000..eee67138071
--- /dev/null
+++ b/packages/react/src/Select/Select.docs.ts
@@ -0,0 +1,53 @@
+import {defineComponent} from '../docs/component'
+
+export default defineComponent({
+ id: 'select',
+ name: 'Select',
+ status: 'alpha',
+ a11yReviewed: '2025-01-08',
+ stories: [
+ 'components-select--default',
+ 'components-select-features--with-option-groups',
+ 'components-select-features--disabled',
+ 'components-select-features--with-caption',
+ 'components-select-features--visually-hidden-label',
+ 'components-select-features--error',
+ 'components-select-features--success',
+ 'components-select-features--block',
+ 'components-select-features--small',
+ 'components-select-features--large',
+ 'components-select-features--with-custom-styling',
+ 'components-select-features--with-placeholder-option',
+ ],
+ importPath: '@primer/react',
+ props: [
+ {
+ name: 'block',
+ type: 'boolean',
+ defaultValue: 'false',
+ description: 'Creates a full width input element',
+ required: false,
+ },
+ {
+ name: 'placeholder',
+ type: 'string',
+ description:
+ "Placeholder text to show when no option is selected.\nThis option is hidden from the dropdown menu when the 'required' prop is set",
+ required: false,
+ },
+ {
+ name: 'size',
+ type: "'small' | 'medium' | 'large'",
+ defaultValue: '',
+ description: 'Creates a smaller or larger input than the default.',
+ required: false,
+ },
+ {
+ name: 'validationStatus',
+ type: "'error' | 'success'",
+ description: 'Style the input to match the status',
+ required: false,
+ },
+ ],
+ subcomponents: [],
+})
diff --git a/packages/react/src/SelectPanel/SelectPanel.docs.ts b/packages/react/src/SelectPanel/SelectPanel.docs.ts
new file mode 100644
index 00000000000..c981ccaa6cb
--- /dev/null
+++ b/packages/react/src/SelectPanel/SelectPanel.docs.ts
@@ -0,0 +1,259 @@
+import {defineComponent} from '../docs/component'
+
+export default defineComponent({
+ id: 'select_panel',
+ docsId: 'select_panel',
+ name: 'SelectPanel',
+ status: 'alpha',
+ a11yReviewed: '2025-01-08',
+ stories: [
+ 'components-selectpanel--default',
+ 'components-selectpanel-features--with-item-dividers',
+ 'components-selectpanel-features--with-placeholder-for-search-input',
+ 'components-selectpanel-features--single-select',
+ 'components-selectpanel-features--multi-select',
+ 'components-selectpanel-features--with-external-anchor',
+ 'components-selectpanel-features--with-secondary-action-button',
+ 'components-selectpanel-features--with-secondary-action-link',
+ 'components-selectpanel-features--with-groups',
+ ],
+ importPath: '@primer/react',
+ props: [
+ {
+ name: 'items',
+ type: 'Array',
+ required: true,
+ description: 'A collection of `Item` props and `Item`-level custom `Item` renderers.',
+ },
+ {
+ name: 'title',
+ type: 'string | React.ReactElement',
+ defaultValue: '"Select an item" or "Select items"',
+ description: 'A descriptive title for the panel',
+ required: false,
+ },
+ {
+ name: 'subtitle',
+ type: 'string | React.ReactElement',
+ description: 'When provided, a subtitle is displayed below the title',
+ required: false,
+ },
+ {
+ name: 'onOpenChange',
+ type: "( open: boolean, gesture: | 'anchor-click' | 'anchor-key-press' | 'click-outside' | 'escape' | 'selection' | 'cancel' ) => void",
+ required: true,
+ description: '',
+ },
+ {
+ name: 'placeholder',
+ type: 'string',
+ description: 'Text used in anchor when there are no selected items',
+ required: false,
+ },
+ {
+ name: 'placeholderText',
+ type: 'string',
+ defaultValue: 'Filter items',
+ description: 'Text used as placeholder for search input',
+ required: false,
+ },
+ {
+ name: 'inputLabel',
+ type: 'string',
+ defaultValue: 'Same as placeholderText',
+ description: 'The aria-label for the filter input',
+ required: false,
+ },
+ {
+ name: 'aria-label',
+ type: 'string',
+ description: 'aria-label to attach to the base DOM node of the list',
+ required: false,
+ },
+ {
+ name: 'filterValue',
+ type: 'string',
+ description: 'The current value of the search input',
+ defaultValue: '',
+ required: false,
+ },
+ {
+ name: 'selected',
+ type: 'ItemInput | Array | undefined',
+ required: true,
+ description: 'Specify the selected item(s)',
+ },
+ {
+ name: 'open',
+ type: 'boolean',
+ required: true,
+ description: 'Determines whether the overlay portion of the component should be shown or not',
+ },
+ {
+ name: 'anchorId',
+ type: 'string',
+ description: 'An override to the internal id that will be spread on to the renderAnchor',
+ defaultValue: '',
+ required: false,
+ },
+ {
+ name: 'anchorRef',
+ type: 'RefObject',
+ description:
+ 'An override to the internal renderAnchor ref that will be used to position the overlay.\nWhen renderAnchor is null this can be used to make an anchor that is detached from ActionMenu.\nAn override to the internal ref that will be spread on to the renderAnchor',
+ required: false,
+ },
+ {
+ name: 'onSelectedChange',
+ type: '(selected: ItemInput | Array) => void',
+ required: true,
+ description: 'Provide a callback called when the selected item(s) change',
+ },
+ {
+ name: 'onFilterChange',
+ type: '(value: string, e: ChangeEvent) => void',
+ description: 'Callback when the search input changes',
+ required: true,
+ },
+ {
+ name: 'onCancel',
+ type: '() => void',
+ description: '(Narrow screens and variant=modal) Callback when the user hits cancel or close',
+ required: false,
+ },
+ {
+ name: 'overlayProps',
+ type: 'Partial',
+ description: 'See [Overlay props](/react/Overlay#props).',
+ required: false,
+ },
+ {
+ name: 'textInputProps',
+ type: "Partial>",
+ description:
+ 'See [TextInput props](/react/TextInput#props). The filter input uses the normal TextInput background by default. Enable `primer_react_select_panel_legacy_contrast` to restore the previous contrast background. An explicit `textInputProps.contrast` value takes precedence over the flag: `true` enables contrast, while `false` or explicitly passing `undefined` disables it. The `contrast` prop remains deprecated.',
+ required: false,
+ },
+ {
+ name: 'variant',
+ type: "'anchored' | 'modal'",
+ description: 'Anchored by default, SelectPanel can be opened as a modal',
+ defaultValue: "'anchored'",
+ required: false,
+ },
+ {
+ name: 'footer',
+ type: 'string | React.ReactElement',
+ defaultValue: 'null',
+ description: 'Please use `secondaryAction` instead.',
+ deprecated: true,
+ required: false,
+ },
+ {
+ name: 'message',
+ type: "{title: string | React.ReactElement; variant: 'empty' | 'error' | 'warning'; body: React.ReactNode; icon?:React.ComponentType;action?: React.ReactElement;}",
+ defaultValue:
+ 'A default empty message is provided if this option is not configured. Supply a custom empty message to override the default.',
+ description: 'Message to display in the panel in case of error or empty results',
+ required: false,
+ },
+ {
+ name: 'notice',
+ type: "{text: string | React.ReactElement; variant: 'empty' | 'error' | 'warning';}",
+ description: 'Optional notice to display on top of the panel',
+ required: false,
+ },
+ {
+ name: 'secondaryAction',
+ type: 'React.ReactElement',
+ defaultValue: 'null',
+ description:
+ 'Secondary action, it will be rendered in the footer of the panel. Use `SecondaryActionButton` or `SecondaryActionLink` for the action.',
+ required: false,
+ },
+ {
+ name: 'showSelectedOptionsFirst',
+ type: 'boolean',
+ description: 'Whether to display the selected items at the top of the list',
+ defaultValue: 'true',
+ required: false,
+ },
+ {
+ name: 'showSelectAll',
+ type: 'boolean',
+ defaultValue: 'false',
+ description:
+ "When `true` and on a multi-select SelectPanel, displays a 'Select all' checkbox that allows users to select or deselect all visible items at once. The checkbox label automatically toggles between 'Select all' and 'Deselect all' based on the current selection state, and shows an indeterminate state when some items are selected.",
+ required: false,
+ },
+ {
+ name: 'disableFullscreenOnNarrow',
+ type: 'boolean',
+ description:
+ 'Whether to disable fullscreen behavior on narrow viewports. When `true`, the panel will maintain its anchored position regardless of viewport size. When `false`, the panel will go fullscreen on narrow viewports (if feature flag is enabled).',
+ defaultValue: 'undefined (uses feature flag default)',
+ required: false,
+ },
+ {
+ name: 'loading',
+ type: 'boolean',
+ defaultValue: 'false',
+ description:
+ 'Whether the panel is in a loading state. When `true`, the panel will display a loading spinner. If `loading` is not provided, the panel will infer the loading state based on the contents of `items` available.',
+ required: false,
+ },
+ {
+ name: 'align',
+ type: "'start' | 'end' | 'center'",
+ defaultValue: "'start'",
+ description:
+ "Determines the alignment of the panel relative to the anchor. Defaults to 'start' which aligns the left edge of the panel with the left edge of the anchor.",
+ required: false,
+ },
+ {
+ name: 'scrollContainerRef',
+ type: 'React.Ref',
+ defaultValue: 'undefined',
+ description: 'A ref assigned to the scrollable container wrapping the ActionList',
+ required: false,
+ },
+ {
+ name: 'actionListProps',
+ type: 'Partial',
+ defaultValue: 'undefined',
+ description: 'See [ActionList props](/react/ActionList#props).',
+ required: false,
+ },
+ {
+ name: 'focusOutBehavior',
+ type: "'start' | 'wrap'",
+ defaultValue: "'wrap'",
+ description: 'Determines how keyboard focus behaves when navigating beyond the first or last item in the list.',
+ required: false,
+ },
+ {
+ name: 'onActiveDescendantChanged',
+ type: '(newActiveDescendant: HTMLElement | undefined, previousActiveDescendant: HTMLElement | undefined, directlyActivated: boolean) => void | undefined',
+ defaultValue: 'undefined',
+ description: 'Callback function that is called when the active descendant changes.',
+ required: false,
+ },
+ {
+ name: 'virtualized',
+ type: 'boolean',
+ defaultValue: 'false',
+ description:
+ 'If true, enables client-side list virtualization. Only the visible items plus a small overscan buffer are rendered in the DOM, dramatically improving performance for large lists. Recommended for lists with more than 100 items. Has no effect when `groupMetadata` is provided.',
+ required: false,
+ },
+ {
+ name: 'displayInViewport',
+ type: 'boolean',
+ defaultValue: 'false',
+ description:
+ 'If true, the panel will attempt to fit entirely into the visible viewport, without having to scroll.',
+ required: false,
+ },
+ ],
+ subcomponents: [],
+})
diff --git a/packages/react/src/SideNav.docs.ts b/packages/react/src/SideNav.docs.ts
new file mode 100644
index 00000000000..029a99ac50a
--- /dev/null
+++ b/packages/react/src/SideNav.docs.ts
@@ -0,0 +1,133 @@
+import {defineComponent} from './docs/component'
+
+export default defineComponent({
+ id: 'side_nav',
+ name: 'SideNav',
+ status: 'deprecated',
+ a11yReviewed: false,
+ importPath: '@primer/react',
+ stories: [
+ 'deprecated-components-sidenav-dev--default',
+ 'deprecated-components-sidenav-dev--full-variant',
+ 'deprecated-components-sidenav-dev--lightweight-variant',
+ 'deprecated-components-sidenav-dev--lightweight-nested-variant',
+ ],
+ props: [
+ {
+ name: 'children',
+ type: 'React.ReactNode',
+ description: 'The navigation content, typically `SideNav.Link` items. Use `NavList` for new navigation.',
+ required: false,
+ },
+ {
+ name: 'as',
+ type: 'React.ElementType',
+ description: 'Render a different element or component instead of the navigation landmark.',
+ required: false,
+ defaultValue: "'nav'",
+ },
+ {
+ name: 'variant',
+ type: "'lightweight' | 'normal'",
+ description: 'Choose the visual style of the navigation.',
+ required: false,
+ defaultValue: "'normal'",
+ },
+ {
+ name: 'bordered',
+ type: 'boolean',
+ description: 'Show a border around the navigation.',
+ required: false,
+ },
+ {
+ name: 'className',
+ type: 'string',
+ description: 'An additional class name for the navigation.',
+ required: false,
+ },
+ {
+ name: 'aria-label',
+ type: 'string',
+ description: 'The accessible name of the navigation landmark.',
+ required: false,
+ },
+ ],
+ subcomponents: [
+ {
+ name: 'SideNav.Link',
+ displayName: 'Link',
+ props: [
+ {name: 'children', type: 'React.ReactNode', description: 'The navigation link content.', required: false},
+ {
+ name: 'href',
+ type: 'string',
+ description: 'The URL to navigate to when rendering an anchor.',
+ required: false,
+ },
+ {
+ name: 'as',
+ type: 'React.ElementType',
+ description: 'Render a different element or component. It should render an anchor or button.',
+ required: false,
+ defaultValue: "'a'",
+ },
+ {
+ name: 'selected',
+ type: 'boolean',
+ description: 'Mark this link as the current page unless `aria-current` is supplied.',
+ required: false,
+ },
+ {
+ name: 'to',
+ type: 'To',
+ description:
+ 'A string marks this link as the current page unless `aria-current` is supplied. This prop is not forwarded.',
+ required: false,
+ },
+ {
+ name: 'aria-current',
+ type: "boolean | 'page' | 'step' | 'location' | 'date' | 'time' | 'true' | 'false'",
+ description: 'Override the current-page state inferred from `selected` or a string `to`.',
+ required: false,
+ },
+ {
+ name: 'variant',
+ type: "'full' | 'normal'",
+ description: 'Use `full` to lay out the link content in a row with space between items.',
+ required: false,
+ },
+ {
+ name: 'className',
+ type: 'string',
+ description: 'An additional class name for the link.',
+ required: false,
+ },
+ {
+ name: 'muted',
+ type: 'boolean',
+ description: 'Use the muted link style.',
+ required: false,
+ },
+ {
+ name: 'inline',
+ type: 'boolean',
+ description: 'Apply the link style for use within text.',
+ required: false,
+ },
+ {
+ name: 'hoverColor',
+ type: 'string',
+ description: 'Deprecated. Use CSS modules to style the hover color.',
+ required: false,
+ },
+ {
+ name: 'ref',
+ type: "SideNavLinkProps['ref']",
+ description: 'A ref to the default anchor.',
+ required: false,
+ },
+ ],
+ passthrough: {element: 'a', url: 'https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attributes'},
+ },
+ ],
+})
diff --git a/packages/react/src/Skeleton/SkeletonBox.docs.ts b/packages/react/src/Skeleton/SkeletonBox.docs.ts
new file mode 100644
index 00000000000..bf8e6c3ce08
--- /dev/null
+++ b/packages/react/src/Skeleton/SkeletonBox.docs.ts
@@ -0,0 +1,44 @@
+import {defineComponent} from '../docs/component'
+
+export default defineComponent({
+ id: 'skeleton_box',
+ name: 'SkeletonBox',
+ status: 'alpha',
+ a11yReviewed: '2025-01-08',
+ stories: [
+ 'components-skeleton-skeletonbox--default',
+ 'components-skeleton-skeletonbox-features--custom-height',
+ 'components-skeleton-skeletonbox-features--custom-width',
+ ],
+ importPath: '@primer/react',
+ props: [
+ {
+ name: 'delay',
+ type: "'short' | 'long' | number",
+ description:
+ "Controls whether and how long to delay rendering the SkeletonBox. Set to 'short' to delay by 300ms, 'long' to delay by 1000ms, or provide a custom number of milliseconds.",
+ defaultValue: 'false',
+ required: false,
+ },
+ {
+ name: 'width',
+ type: 'string',
+ description: 'Width of the skeleton box. Accepts any valid CSS `width` value.',
+ required: false,
+ },
+ {
+ name: 'height',
+ defaultValue: '1rem',
+ type: 'string',
+ description: 'Height of the skeleton box. Accepts any valid CSS `height` value.',
+ required: false,
+ },
+ {
+ name: 'className',
+ type: 'string',
+ description: 'The className of the skeleton box',
+ required: false,
+ },
+ ],
+ subcomponents: [],
+})
diff --git a/packages/react/src/SkeletonAvatar/SkeletonAvatar.docs.ts b/packages/react/src/SkeletonAvatar/SkeletonAvatar.docs.ts
new file mode 100644
index 00000000000..ab6d66c91fd
--- /dev/null
+++ b/packages/react/src/SkeletonAvatar/SkeletonAvatar.docs.ts
@@ -0,0 +1,34 @@
+import {defineComponent} from '../docs/component'
+
+export default defineComponent({
+ id: 'skeleton_avatar',
+ name: 'SkeletonAvatar',
+ status: 'alpha',
+ a11yReviewed: '2025-01-08',
+ stories: [
+ 'components-skeleton-skeletonavatar--default',
+ 'components-skeleton-skeletonavatar-features--square',
+ 'components-skeleton-skeletonavatar-features--size',
+ 'components-skeleton-skeletonavatar-features--size-responsive',
+ 'components-skeleton-skeletonavatar-features--in-a-stack',
+ ],
+ importPath: '@primer/react/experimental',
+ props: [
+ {
+ name: 'size',
+ type: 'number | { narrow?: number; regular?: number; wide?: number; }',
+ defaultValue: '20',
+ description: 'The size of the avatar in pixels.',
+ required: false,
+ },
+ {
+ name: 'square',
+ type: 'boolean',
+ defaultValue: 'false',
+ description: 'If true, the avatar will be square instead of circular.',
+ required: false,
+ },
+ {name: 'className', type: 'string', description: 'Class name for custom styling.', required: false},
+ ],
+ subcomponents: [],
+})
diff --git a/packages/react/src/SkeletonText/SkeletonText.docs.ts b/packages/react/src/SkeletonText/SkeletonText.docs.ts
new file mode 100644
index 00000000000..81cb9a136e3
--- /dev/null
+++ b/packages/react/src/SkeletonText/SkeletonText.docs.ts
@@ -0,0 +1,47 @@
+import {defineComponent} from '../docs/component'
+
+export default defineComponent({
+ id: 'skeleton_text',
+ name: 'SkeletonText',
+ status: 'alpha',
+ a11yReviewed: '2025-01-08',
+ stories: [
+ 'components-skeleton-skeletontext--default',
+ 'components-skeleton-skeletontext-features--with-max-width',
+ 'components-skeleton-skeletontext-features--with-multiple-lines',
+ 'components-skeleton-skeletontext-features--display',
+ 'components-skeleton-skeletontext-features--subtitle',
+ 'components-skeleton-skeletontext-features--title-large',
+ 'components-skeleton-skeletontext-features--title-medium',
+ 'components-skeleton-skeletontext-features--title-small',
+ 'components-skeleton-skeletontext-features--body-large',
+ 'components-skeleton-skeletontext-features--body-medium',
+ 'components-skeleton-skeletontext-features--body-small',
+ ],
+ importPath: '@primer/react/experimental',
+ props: [
+ {
+ name: 'size',
+ defaultValue: "'bodyMedium'",
+ type: "'display' | 'titleLarge' | 'titleMedium' | 'titleSmall' | 'bodyLarge' | 'bodyMedium' | 'bodySmall' | 'subtitle'",
+ description: 'Size of the text that the skeleton is replacing.',
+ required: false,
+ },
+ {
+ name: 'lines',
+ defaultValue: '1',
+ type: 'number',
+ description: 'Number of lines of skeleton text to render.',
+ required: false,
+ },
+ {
+ name: 'maxWidth',
+ type: 'string',
+ description:
+ 'Maximum width that the line(s) of skeleton text can take up. Accepts any valid CSS `max-width` value.',
+ required: false,
+ },
+ {name: 'className', type: 'string', description: 'Class name for custom styling.', required: false},
+ ],
+ subcomponents: [],
+})
diff --git a/packages/react/src/Spinner/Spinner.docs.ts b/packages/react/src/Spinner/Spinner.docs.ts
new file mode 100644
index 00000000000..976f830fb6e
--- /dev/null
+++ b/packages/react/src/Spinner/Spinner.docs.ts
@@ -0,0 +1,55 @@
+import {defineComponent} from '../docs/component'
+
+export default defineComponent({
+ a11yReviewed: '2025-01-08',
+ id: 'spinner',
+ importPath: '@primer/react',
+ name: 'Spinner',
+ props: [
+ {
+ description: 'Sets the width and height of the spinner.',
+ name: 'size',
+ type: "'small' | 'medium' | 'large'",
+ required: false,
+ },
+ {
+ defaultValue: 'Loading',
+ description:
+ 'Sets the text conveyed by assistive technologies such as screen readers. Set to `null` if the loading state is displayed in a text node somewhere else on the page.',
+ name: 'srText',
+ type: 'string | null',
+ required: false,
+ },
+ {
+ deprecated: true,
+ description: 'Sets the text conveyed by assistive technologies such as screen readers.',
+ name: 'aria-label',
+ type: 'string',
+ required: false,
+ },
+ {description: '', name: 'className', type: 'string', required: false},
+ {
+ name: 'data-*',
+ type: 'string',
+ description: 'Custom data attributes forwarded to the spinner SVG.',
+ required: false,
+ },
+ {
+ defaultValue: 'false',
+ description:
+ "Controls whether and how long to delay rendering the spinner. Set to `true` to delay by 1000ms, `'short'` to delay by 300ms, `'long'` to delay by 1000ms, or provide a custom number of milliseconds.",
+ name: 'delay',
+ type: "boolean | 'short' | 'long' | number",
+ required: false,
+ },
+ ],
+ status: 'alpha',
+ stories: [
+ 'components-spinner--default',
+ 'components-spinner-features--small',
+ 'components-spinner-features--large',
+ 'components-spinner-features--suppress-screen-reader-text',
+ 'components-spinner-features--with-delay',
+ ],
+ subcomponents: [],
+})
diff --git a/packages/react/src/SplitPageLayout/SplitPageLayout.docs.ts b/packages/react/src/SplitPageLayout/SplitPageLayout.docs.ts
new file mode 100644
index 00000000000..16e7f63576c
--- /dev/null
+++ b/packages/react/src/SplitPageLayout/SplitPageLayout.docs.ts
@@ -0,0 +1,346 @@
+import {defineComponent} from '../docs/component'
+
+export default defineComponent({
+ id: 'split_page_layout',
+ name: 'SplitPageLayout',
+ status: 'alpha',
+ a11yReviewed: '2025-01-08',
+ stories: [
+ 'components-splitpagelayout--default',
+ 'components-splitpagelayout-features--settings-page',
+ 'components-splitpagelayout-features--with-sidebar-start',
+ 'components-splitpagelayout-features--with-sidebar-end',
+ 'components-splitpagelayout-features--with-resizable-sidebar',
+ 'components-splitpagelayout-features--with-sidebar-and-resizable-pane',
+ 'components-splitpagelayout-features--with-sticky-sidebar',
+ 'components-splitpagelayout-features--sidebar-fullscreen-responsive-variant',
+ ],
+ importPath: '@primer/react',
+ props: [
+ {
+ name: 'className',
+ type: 'string',
+ description: 'Additional CSS class names for the layout container.',
+ required: false,
+ },
+ ],
+ subcomponents: [
+ {
+ name: 'SplitPageLayout.Header',
+ props: [
+ {
+ name: 'aria-label',
+ type: 'string',
+ description: 'A unique label for the rendered main landmark',
+ required: false,
+ },
+ {
+ name: 'aria-labelledby',
+ type: 'string',
+ description: 'An id to an element which uniquely labels the rendered main landmark',
+ required: false,
+ },
+ {
+ name: 'padding',
+ type: "| 'none' | 'condensed' | 'normal'",
+ defaultValue: "'normal'",
+ description: 'The amount of padding inside the header.',
+ required: false,
+ },
+ {
+ name: 'divider',
+ type: "| 'none' | 'line' | { narrow?: | 'none' | 'line' | 'filled' regular?: | 'none' | 'line' wide?: | 'none' | 'line' }",
+ defaultValue: "'line'",
+ description: '',
+ required: false,
+ },
+ {
+ name: 'hidden',
+ type: '| boolean | { narrow?: boolean regular?: boolean wide?: boolean }',
+ defaultValue: 'false',
+ description: 'Whether the header is hidden.',
+ required: false,
+ },
+ ],
+ displayName: 'Header',
+ },
+ {
+ name: 'SplitPageLayout.Content',
+ props: [
+ {
+ name: 'aria-label',
+ type: 'string',
+ description: 'A unique label for the rendered main landmark',
+ required: false,
+ },
+ {
+ name: 'aria-labelledby',
+ type: 'string',
+ description: 'An id to an element which uniquely labels the rendered main landmark',
+ required: false,
+ },
+ {
+ name: 'as',
+ type: 'React.ElementType',
+ defaultValue: "'main'",
+ description: 'Change the root node to another HTML element or custom component.',
+ required: false,
+ },
+ {
+ name: 'width',
+ type: "| 'full' | 'medium' | 'large' | 'xlarge'",
+ defaultValue: "'large'",
+ description: 'The maximum width of the content region.',
+ required: false,
+ },
+ {
+ name: 'padding',
+ type: "| 'none' | 'condensed' | 'normal'",
+ defaultValue: "'normal'",
+ description: 'The amount of padding inside the content.',
+ required: false,
+ },
+ {
+ name: 'hidden',
+ type: '| boolean | { narrow?: boolean regular?: boolean wide?: boolean }',
+ defaultValue: 'false',
+ description: 'Whether the content is hidden.',
+ required: false,
+ },
+ ],
+ displayName: 'Content',
+ },
+ {
+ name: 'SplitPageLayout.Pane',
+ props: [
+ {
+ name: 'aria-label',
+ type: 'string | undefined',
+ description: "Label for the pane. Required if the pane overflows and doesn't have aria-labelledby.",
+ required: false,
+ },
+ {
+ name: 'aria-labelledby',
+ type: 'string | undefined',
+ description:
+ "Id of an element that acts as a label for the pane. Required if the pane overflows and doesn't have aria-label.",
+ required: false,
+ },
+ {
+ name: 'width',
+ type: "| 'small' | 'medium' | 'large' | { min: string max: string default: string }",
+ defaultValue: "'medium'",
+ description:
+ "The width of the pane. If using custom widths, provide an object with keys 'min', 'max' and 'default'.",
+ required: false,
+ },
+ {
+ name: 'minWidth',
+ type: 'number',
+ defaultValue: '256',
+ description: 'The minimum width of the pane.',
+ required: false,
+ },
+ {
+ name: 'resizable',
+ type: 'boolean',
+ defaultValue: 'false',
+ description:
+ 'When true, the pane may be resized by the user. Uses localStorage persistence by default. Note: with default persistence in SSR, the server-rendered width may differ from the stored client width, causing a brief layout shift on hydration. Use `onResizeEnd` with server-aware storage to avoid this.',
+ required: false,
+ },
+ {
+ name: 'currentWidth',
+ type: 'number | undefined',
+ description:
+ 'Current/controlled width value in pixels. Required when `onResizeEnd` is provided. Pass `undefined` when the persisted value has not loaded yet. The `width` prop still defines the default used when resetting (e.g., double-click).',
+ required: false,
+ },
+ {
+ name: 'onResizeEnd',
+ type: '(width: number) => void',
+ description:
+ 'Callback fired when a resize operation ends (drag release or keyboard key up). When provided, replaces localStorage persistence. Requires `currentWidth`.',
+ required: false,
+ },
+ {
+ name: 'widthStorageKey',
+ type: 'string',
+ defaultValue: "'paneWidth'",
+ description:
+ 'localStorage key used to persist the pane width across sessions. Only applies when `resizable` is `true` and no `onResizeEnd` callback is provided.',
+ required: false,
+ },
+ {
+ name: 'sticky',
+ type: 'boolean',
+ defaultValue: 'true',
+ description: 'Whether the pane should stick to the top of the screen while the content scrolls.',
+ required: false,
+ },
+ {
+ name: 'offsetHeader',
+ type: 'number | string',
+ defaultValue: '0',
+ description:
+ 'Use offsetHeader along with the sticky prop to push the sticky pane down to make room for a sticky header if necessary. Use the type `string` to specify the height with a unit i.e. 5rem; otherwise the type `number` will be taken as px.',
+ required: false,
+ },
+ {
+ name: 'padding',
+ type: "| 'none' | 'condensed' | 'normal'",
+ defaultValue: "'normal'",
+ description: 'The amount of padding inside the pane.',
+ required: false,
+ },
+ {
+ name: 'divider',
+ type: "| 'none' | 'line' | { narrow?: | 'none' | 'line' | 'filled' regular?: | 'none' | 'line' wide?: | 'none' | 'line' }",
+ defaultValue: "'line'",
+ description: '',
+ required: false,
+ },
+ {
+ name: 'hidden',
+ type: '| boolean | { narrow?: boolean regular?: boolean wide?: boolean }',
+ defaultValue: 'false',
+ description: 'Whether the pane is hidden.',
+ required: false,
+ },
+ {
+ name: 'position',
+ type: "'end' | 'start' | {narrow?: 'end' | 'start', narrow?: 'end' | 'start', wide?: 'end' | 'start'}",
+ description: 'Which side of the page the pane should be on. Can be changed for different viewport widths.',
+ defaultValue: 'start',
+ required: false,
+ },
+ ],
+ displayName: 'Pane',
+ },
+ {
+ name: 'SplitPageLayout.Sidebar',
+ props: [
+ {
+ name: 'aria-label',
+ type: 'string | undefined',
+ description: 'A unique label for the sidebar region.',
+ required: false,
+ },
+ {
+ name: 'aria-labelledby',
+ type: 'string | undefined',
+ description: 'An id to an element which uniquely labels the sidebar region.',
+ required: false,
+ },
+ {
+ name: 'position',
+ type: "'start' | 'end'",
+ defaultValue: "'start'",
+ description:
+ 'Position of the sidebar relative to the page layout. The sidebar spans the full height of the layout, adjacent to the header, content, and footer.',
+ required: false,
+ },
+ {
+ name: 'width',
+ type: "| 'small' | 'medium' | 'large' | { min: string max: string default: string }",
+ defaultValue: "'medium'",
+ description:
+ "The width of the sidebar. If using custom widths, provide an object with keys 'min', 'max' and 'default'.",
+ required: false,
+ },
+ {
+ name: 'minWidth',
+ type: 'number',
+ defaultValue: '256',
+ description: 'Minimum width of the sidebar when resizable.',
+ required: false,
+ },
+ {
+ name: 'resizable',
+ type: 'boolean',
+ defaultValue: 'false',
+ description:
+ 'When true, the sidebar may be resized by the user. Width is persisted to localStorage by default.',
+ required: false,
+ },
+ {
+ name: 'padding',
+ type: "| 'none' | 'condensed' | 'normal'",
+ defaultValue: "'normal'",
+ description: 'The amount of padding inside the sidebar.',
+ required: false,
+ },
+ {
+ name: 'divider',
+ type: "| 'none' | 'line'",
+ defaultValue: "'line'",
+ description: 'Divider style between the sidebar and the rest of the layout.',
+ required: false,
+ },
+ {
+ name: 'sticky',
+ type: 'boolean',
+ defaultValue: 'false',
+ description:
+ 'Whether the sidebar sticks to the viewport when scrolling. When enabled, the sidebar uses position: sticky with top: 0 and height: 100vh.',
+ required: false,
+ },
+ {
+ name: 'responsiveVariant',
+ type: "| 'default' | 'fullscreen'",
+ defaultValue: "'default'",
+ description:
+ "Controls sidebar behavior at narrow viewport widths (below 768px). 'default' retains its normal inline layout. 'fullscreen' expands to cover the full viewport like a dialog overlay.",
+ required: false,
+ },
+ {
+ name: 'hidden',
+ type: '| boolean | { narrow?: boolean regular?: boolean wide?: boolean }',
+ defaultValue: 'false',
+ description: 'Whether the sidebar is hidden.',
+ required: false,
+ },
+ ],
+ displayName: 'Sidebar',
+ },
+ {
+ name: 'SplitPageLayout.Footer',
+ props: [
+ {
+ name: 'aria-label',
+ type: 'string',
+ description: 'A unique label for the rendered main landmark',
+ required: false,
+ },
+ {
+ name: 'aria-labelledby',
+ type: 'string',
+ description: 'An id to an element which uniquely labels the rendered main landmark',
+ required: false,
+ },
+ {
+ name: 'padding',
+ type: "| 'none' | 'condensed' | 'normal'",
+ defaultValue: "'normal'",
+ description: 'The amount of padding inside the footer.',
+ required: false,
+ },
+ {
+ name: 'divider',
+ type: "| 'none' | 'line' | { narrow?: | 'none' | 'line' | 'filled' regular?: | 'none' | 'line' wide?: | 'none' | 'line' }",
+ defaultValue: "'line'",
+ description: '',
+ required: false,
+ },
+ {
+ name: 'hidden',
+ type: '| boolean | { narrow?: boolean regular?: boolean wide?: boolean }',
+ defaultValue: 'false',
+ description: 'Whether the footer is hidden.',
+ required: false,
+ },
+ ],
+ displayName: 'Footer',
+ },
+ ],
+})
diff --git a/packages/react/src/Stack/Stack.docs.ts b/packages/react/src/Stack/Stack.docs.ts
new file mode 100644
index 00000000000..1749d9a76c2
--- /dev/null
+++ b/packages/react/src/Stack/Stack.docs.ts
@@ -0,0 +1,94 @@
+import {defineComponent} from '../docs/component'
+
+export default defineComponent({
+ id: 'stack',
+ name: 'Stack',
+ status: 'alpha',
+ a11yReviewed: '2025-01-08',
+ stories: [],
+ importPath: '@primer/react',
+ props: [
+ {
+ name: 'gap',
+ type: "'none' | 'tight' | 'condensed' | 'cozy' | 'normal' | 'spacious' | ResponsiveValue<'none' | 'tight' | 'condensed' | 'cozy' | 'normal' | 'spacious'>",
+ description: 'Specify the gap between children elements in the stack.',
+ required: false,
+ },
+ {
+ name: 'direction',
+ type: "'horizontal' | 'vertical' | ResponsiveValue<'horizontal' | 'vertical'>",
+ description: 'Specify the orientation for the stack container.',
+ required: false,
+ },
+ {
+ name: 'align',
+ type: "'stretch' | 'start' | 'center' | 'end' | 'baseline' | ResponsiveValue<'stretch' | 'start' | 'center' | 'end' | 'baseline'>",
+ description: 'Specify the alignment between items in the cross-axis of the orientation.',
+ required: false,
+ },
+ {
+ name: 'wrap',
+ type: "'wrap' | 'nowrap' | 'balance' | ResponsiveValue<'wrap' | 'nowrap' | 'balance'>",
+ description: 'Specify whether items are forced onto one line or can wrap onto multiple lines.',
+ required: false,
+ },
+ {
+ name: 'justify',
+ type: "'start' | 'center' | 'end' | 'space-between' | 'space-evenly' | ResponsiveValue<'start' | 'center' | 'end' | 'space-between' | 'space-evenly'>",
+ description: 'Specify how items will be distributed in the stacking direction.',
+ required: false,
+ },
+ {
+ name: 'padding',
+ type: "'none' | 'tight' | 'condensed' | 'cozy' | 'normal' | 'spacious' | ResponsiveValue<'none' | 'tight' | 'condensed' | 'cozy' | 'normal' | 'spacious'>",
+ description: 'Specify the padding of the stack container.',
+ required: false,
+ },
+ {
+ name: 'paddingBlock',
+ type: "'none' | 'tight' | 'condensed' | 'cozy' | 'normal' | 'spacious' | ResponsiveValue<'none' | 'tight' | 'condensed' | 'cozy' | 'normal' | 'spacious'>",
+ description:
+ 'Specify the block (vertical) padding of the stack container. Overrides the block axis of padding when both are set.',
+ required: false,
+ },
+ {
+ name: 'paddingInline',
+ type: "'none' | 'tight' | 'condensed' | 'cozy' | 'normal' | 'spacious' | ResponsiveValue<'none' | 'tight' | 'condensed' | 'cozy' | 'normal' | 'spacious'>",
+ description:
+ 'Specify the inline (horizontal) padding of the stack container. Overrides the inline axis of padding when both are set.',
+ required: false,
+ },
+ {
+ name: 'className',
+ type: 'string',
+ description: 'Additional CSS class names for the stack container.',
+ required: false,
+ },
+ ],
+ subcomponents: [
+ {
+ name: 'Stack.Item',
+ props: [
+ {
+ name: 'grow',
+ type: 'boolean | ResponsiveValue',
+ description: 'Allow item to keep size or expand to fill the available space.',
+ required: false,
+ },
+ {
+ name: 'shrink',
+ type: 'boolean | ResponsiveValue',
+ description: 'Allow item to keep size or shrink to fit the available space.',
+ required: false,
+ },
+ {
+ name: 'className',
+ type: 'string',
+ description: 'Additional CSS class names for the stack item.',
+ required: false,
+ },
+ ],
+ displayName: 'Item',
+ },
+ ],
+})
diff --git a/packages/react/src/StateLabel/StateLabel.docs.ts b/packages/react/src/StateLabel/StateLabel.docs.ts
new file mode 100644
index 00000000000..8a31597db79
--- /dev/null
+++ b/packages/react/src/StateLabel/StateLabel.docs.ts
@@ -0,0 +1,54 @@
+import {defineComponent} from '../docs/component'
+
+export default defineComponent({
+ id: 'state_label',
+ name: 'StateLabel',
+ status: 'alpha',
+ a11yReviewed: '2025-01-08',
+ stories: [
+ 'components-statelabel--default',
+ 'components-statelabel-features--issue-opened',
+ 'components-statelabel-features--issue-closed',
+ 'components-statelabel-features--issue-closed-not-planned',
+ 'components-statelabel-features--issue-draft',
+ 'components-statelabel-features--pull-opened',
+ 'components-statelabel-features--pull-closed',
+ 'components-statelabel-features--pull-merged',
+ 'components-statelabel-features--queued',
+ 'components-statelabel-features--draft',
+ 'components-statelabel-features--unavailable',
+ 'components-statelabel-features--alert-opened',
+ 'components-statelabel-features--alert-fixed',
+ 'components-statelabel-features--alert-dismissed',
+ 'components-statelabel-features--alert-closed',
+ 'components-statelabel-features--small',
+ 'components-statelabel-features--open',
+ 'components-statelabel-features--closed',
+ 'components-statelabel-features--archived',
+ ],
+ importPath: '@primer/react',
+ props: [
+ {
+ name: 'size',
+ type: "'small' | 'medium'",
+ defaultValue: "'medium'",
+ description: 'Sets the size of the state label.',
+ required: false,
+ },
+ {
+ name: 'variant',
+ type: "'small' | 'normal'",
+ defaultValue: "'normal'",
+ description: 'Use `size` instead.',
+ deprecated: true,
+ required: false,
+ },
+ {
+ name: 'status',
+ type: "'issueOpened' | 'issueClosed' | 'issueClosedNotPlanned' | 'pullOpened' | 'pullClosed' | 'pullMerged' | 'draft' | 'issueDraft' | 'pullQueued' | 'unavailable' | 'alertOpened' | 'alertFixed' | 'alertDismissed' | 'alertClosed' | 'open' | 'closed' | 'archived'",
+ required: true,
+ description: 'The status represented by the label. Determines the icon and visual treatment.',
+ },
+ ],
+ subcomponents: [],
+})
diff --git a/packages/react/src/SubNav/SubNav.docs.ts b/packages/react/src/SubNav/SubNav.docs.ts
new file mode 100644
index 00000000000..ea56f770edf
--- /dev/null
+++ b/packages/react/src/SubNav/SubNav.docs.ts
@@ -0,0 +1,64 @@
+import {defineComponent} from '../docs/component'
+
+export default defineComponent({
+ id: 'sub_nav',
+ name: 'SubNav',
+ status: 'alpha',
+ a11yReviewed: '2025-01-08',
+ stories: ['components-subnav--default', 'components-subnav-features--selected'],
+ importPath: '@primer/react',
+ props: [
+ {
+ name: 'actions',
+ type: 'React.ReactNode',
+ description: 'Place another element, such as a button, to the opposite side of the navigation items.',
+ required: false,
+ },
+ {
+ name: 'align',
+ type: "'right'",
+ description: 'Use `right` to have navigation items aligned right.',
+ required: false,
+ },
+ {
+ name: 'full',
+ type: 'boolean',
+ description: 'Used to make navigation fill the width of the container.',
+ required: false,
+ },
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Used to set the `aria-label` on the top level `` element.',
+ required: false,
+ },
+ {
+ name: 'aria-label',
+ type: 'string',
+ description: 'Used to set the `aria-label` on the top level `` element.',
+ required: false,
+ },
+ ],
+ subcomponents: [
+ {
+ name: 'SubNav.Link',
+ props: [
+ {name: 'href', type: 'string', description: 'URL the anchor links to.', required: false},
+ {
+ name: 'selected',
+ type: 'boolean',
+ description: 'Whether this item represents the current page',
+ required: false,
+ },
+ {
+ name: 'to',
+ type: 'string | Partial',
+ description: 'Passed through to the native anchor. Use `href` for navigation.',
+ required: false,
+ },
+ ],
+ displayName: 'Link',
+ },
+ {name: 'SubNav.Links', props: [], displayName: 'Links'},
+ ],
+})
diff --git a/packages/react/src/TabNav/TabNav.docs.ts b/packages/react/src/TabNav/TabNav.docs.ts
new file mode 100644
index 00000000000..48a826217ce
--- /dev/null
+++ b/packages/react/src/TabNav/TabNav.docs.ts
@@ -0,0 +1,47 @@
+import {defineComponent} from '../docs/component'
+
+export default defineComponent({
+ id: 'tab_nav',
+ name: 'TabNav',
+ status: 'deprecated',
+ a11yReviewed: false,
+ stories: ['deprecated-components-tabnav--default', 'deprecated-components-tabnav-features--selected'],
+ importPath: '@primer/react/deprecated',
+ props: [
+ {
+ name: 'aria-label',
+ type: 'string',
+ description: 'Used to set the `aria-label` on the top level `` element.',
+ required: false,
+ },
+ ],
+ subcomponents: [
+ {
+ name: 'TabNav.Link',
+ props: [
+ {
+ name: 'as',
+ type: 'React.ElementType',
+ defaultValue: "'a'",
+ description: 'The element or component to render for the tab.',
+ required: false,
+ },
+ {
+ name: 'href',
+ type: 'string',
+ description: 'The URL the tab links to when rendered as an anchor.',
+ required: false,
+ },
+ {name: 'selected', type: 'boolean', description: 'Whether this is the selected tab.', required: false},
+ {
+ name: 'to',
+ type: 'string | Partial',
+ description:
+ "Used when the item is rendered using a component like React Router's `Link`. The path to navigate to.",
+ required: false,
+ },
+ ],
+ displayName: 'Link',
+ },
+ ],
+})
diff --git a/packages/react/src/Text/Text.docs.ts b/packages/react/src/Text/Text.docs.ts
new file mode 100644
index 00000000000..cb76ea78703
--- /dev/null
+++ b/packages/react/src/Text/Text.docs.ts
@@ -0,0 +1,49 @@
+import {defineComponent} from '../docs/component'
+
+export default defineComponent({
+ id: 'text',
+ name: 'Text',
+ status: 'alpha',
+ a11yReviewed: '2025-01-08',
+ stories: [
+ 'components-text--default',
+ 'components-text-features--polymorphism',
+ 'components-text-features--styled-text',
+ 'components-text-features--size-small',
+ 'components-text-features--size-medium',
+ 'components-text-features--size-large',
+ 'components-text-features--light-weight',
+ 'components-text-features--normal-weight',
+ 'components-text-features--medium-weight',
+ 'components-text-features--semibold-weight',
+ 'components-text-features--pre-white-space',
+ 'components-text-features--normal-white-space',
+ 'components-text-features--nowrap-white-space',
+ 'components-text-features--pre-wrap-white-space',
+ 'components-text-features--pre-line-white-space',
+ ],
+ importPath: '@primer/react',
+ props: [
+ {
+ name: 'as',
+ defaultValue: "'span'",
+ type: 'React.ElementType',
+ description: 'The element or component to render for the text.',
+ required: false,
+ },
+ {name: 'size', type: "'large' | 'medium' | 'small'", description: 'Sets the font size.', required: false},
+ {
+ name: 'weight',
+ type: "'light' | 'normal' | 'medium' | 'semibold'",
+ description: 'Sets the font weight.',
+ required: false,
+ },
+ {
+ name: 'whiteSpace',
+ type: "'pre' | 'normal' | 'nowrap' | 'pre-wrap' | 'pre-line'",
+ description: 'Controls how whitespace and line wrapping are handled.',
+ required: false,
+ },
+ ],
+ subcomponents: [],
+})
diff --git a/packages/react/src/TextInput/TextInput.docs.ts b/packages/react/src/TextInput/TextInput.docs.ts
new file mode 100644
index 00000000000..205f999199f
--- /dev/null
+++ b/packages/react/src/TextInput/TextInput.docs.ts
@@ -0,0 +1,209 @@
+import {defineComponent} from '../docs/component'
+
+export default defineComponent({
+ id: 'text_input',
+ name: 'TextInput',
+ status: 'alpha',
+ a11yReviewed: '2025-01-08',
+ stories: [
+ 'components-textinput--default',
+ 'components-textinput-features--disabled',
+ 'components-textinput-features--with-caption',
+ 'components-textinput-features--visually-hidden-label',
+ 'components-textinput-features--error',
+ 'components-textinput-features--success',
+ 'components-textinput-features--block',
+ 'components-textinput-features--small',
+ 'components-textinput-features--large',
+ 'components-textinput-features--required',
+ 'components-textinput-features--with-leading-visual',
+ 'components-textinput-features--with-trailing-icon',
+ 'components-textinput-features--with-trailing-action',
+ 'components-textinput-features--with-tooltip-direction',
+ 'components-textinput-features--with-loading-indicator',
+ 'components-textinput-features--with-autocomplete-attribute',
+ ],
+ importPath: '@primer/react',
+ props: [
+ {
+ name: 'aria-label',
+ type: 'string',
+ defaultValue: '',
+ description: 'Gives the input an accessible name.',
+ required: false,
+ },
+ {
+ name: 'autoComplete',
+ type: 'string',
+ description: 'Allows input to autofill based on value given.',
+ required: false,
+ },
+ {
+ name: 'block',
+ type: 'boolean',
+ defaultValue: 'false',
+ description: 'Creates a full-width input element',
+ required: false,
+ },
+ {
+ name: 'characterLimit',
+ type: 'number',
+ description: 'The maximum number of characters allowed in the input',
+ required: false,
+ },
+ {
+ name: 'contrast',
+ type: 'boolean',
+ defaultValue: 'false',
+ deprecated: true,
+ description: 'Deprecated. Omit this prop to use the default background.',
+ required: false,
+ },
+ {
+ name: 'size',
+ type: "'small' | 'medium' | 'large'",
+ defaultValue: '',
+ description: 'Creates a smaller or larger input than the default.',
+ required: false,
+ },
+ {
+ name: 'loading',
+ type: 'boolean',
+ description: 'Whether to show a loading indicator in the input',
+ required: false,
+ },
+ {
+ name: 'loaderPosition',
+ type: "'auto' | 'leading' | 'trailing'",
+ defaultValue: '',
+ description:
+ "Which position to render the loading indicator\n\n- 'auto' (default): at the end of the input, unless a `leadingVisual` is passed. Then, it will render at the beginning\n- 'leading': at the beginning of the input\n- 'trailing': at the end of the input",
+ required: false,
+ },
+ {
+ name: 'loaderText',
+ type: 'string',
+ defaultValue: 'Loading',
+ description:
+ 'Text for screen readers to convey the loading state, should be descriptive and explain what is loading. This prop should only be used if there is visible context explaining what is loading, to ensure that context is provided to all users.',
+ required: false,
+ },
+ {
+ name: 'leadingVisual',
+ type: 'string | React.ComponentType',
+ description: 'Visual positioned on the left edge inside the input',
+ required: false,
+ },
+ {
+ name: 'monospace',
+ type: 'boolean',
+ defaultValue: 'false',
+ description: 'Shows input in monospace font',
+ required: false,
+ },
+ {
+ name: 'trailingVisual',
+ type: 'string | React.ComponentType',
+ description: 'Visual positioned on the right edge inside the input',
+ required: false,
+ },
+ {
+ name: 'trailingAction',
+ type: 'React.ReactElement>',
+ description: 'A visual that renders inside the input after the typing area',
+ required: false,
+ },
+ {
+ name: 'validationStatus',
+ type: "'error' | 'success'",
+ description: 'Style the input to match the status',
+ required: false,
+ },
+ {
+ name: 'variant',
+ type: "'small' | 'medium' | 'large'",
+ defaultValue: '',
+ deprecated: true,
+ description: '(Use size) Creates a smaller or larger input than the default.',
+ required: false,
+ },
+ {
+ name: 'width',
+ type: 'string | number',
+ defaultValue: '',
+ deprecated: true,
+ description: '(Use css modules) Set the width of the input',
+ required: false,
+ },
+ {
+ name: 'maxWidth',
+ type: 'string | number',
+ deprecated: true,
+ description: '(Use css modules) Set the maximum width of the input',
+ required: false,
+ },
+ {
+ name: 'minWidth',
+ type: 'string | number',
+ deprecated: true,
+ description: '(Use css modules) Set the minimum width of the input',
+ required: false,
+ },
+ {
+ name: 'icon',
+ type: 'React.ComponentType',
+ deprecated: true,
+ description:
+ '(Use leadingVisual or trailingVisual) An Octicon React component. To be used inside of input. Positioned on the left edge.',
+ required: false,
+ },
+ {name: 'ref', type: 'React.RefObject', required: false, description: 'Ref to the .'},
+ ],
+ subcomponents: [
+ {
+ name: 'TextInput.Action',
+ props: [
+ {
+ name: 'aria-label',
+ type: 'string',
+ description:
+ 'Text that appears in a tooltip. If an icon is passed, this is also used as the label used by assistive technologies.',
+ required: false,
+ },
+ {
+ name: 'tooltipDirection',
+ type: "'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w' | 'nw'",
+ defaultValue: 's',
+ description: 'Sets where the tooltip renders in relation to the target.',
+ required: false,
+ },
+ {
+ name: 'icon',
+ type: 'React.FunctionComponent',
+ description: 'The icon to render inside the button',
+ required: false,
+ },
+ {
+ name: 'variant',
+ type: "'default' | 'primary' | 'invisible' | 'danger'",
+ defaultValue: '',
+ deprecated: true,
+ description: "(Deprecated so that only the 'invisible' variant is used) Determine's the styles on a button",
+ required: false,
+ },
+ {
+ name: 'ref',
+ type: 'React.RefObject',
+ required: false,
+ description:
+ 'Allows getting a ref to the component instance.\nOnce the component unmounts, React will set `ref.current` to `null`\n(or call the ref with `null` if you passed a callback ref).',
+ },
+ ],
+ passthrough: {
+ element: 'button',
+ url: 'https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes',
+ },
+ displayName: 'Action',
+ },
+ ],
+})
diff --git a/packages/react/src/TextInputWithTokens/TextInputWithTokens.docs.ts b/packages/react/src/TextInputWithTokens/TextInputWithTokens.docs.ts
new file mode 100644
index 00000000000..b0427703ee8
--- /dev/null
+++ b/packages/react/src/TextInputWithTokens/TextInputWithTokens.docs.ts
@@ -0,0 +1,84 @@
+import {defineComponent} from '../docs/component'
+
+export default defineComponent({
+ id: 'text_input_with_tokens',
+ name: 'TextInputWithTokens',
+ status: 'deprecated',
+ a11yReviewed: '2025-01-08',
+ stories: [
+ 'deprecated-components-textinputwithtokens--default',
+ 'deprecated-components-textinputwithtokens-features--with-leading-visual',
+ 'deprecated-components-textinputwithtokens-features--with-trailing-visual',
+ 'deprecated-components-textinputwithtokens-features--with-loading-indicator',
+ 'deprecated-components-textinputwithtokens-features--using-issue-label-tokens',
+ 'deprecated-components-textinputwithtokens-features--unstyled',
+ 'deprecated-components-textinputwithtokens-features--prevent-tokens-from-wrapping',
+ 'deprecated-components-textinputwithtokens-features--max-height',
+ 'deprecated-components-textinputwithtokens-features--size',
+ 'deprecated-components-textinputwithtokens-features--truncated',
+ ],
+ importPath: '@primer/react',
+ props: [
+ {
+ name: 'tokens',
+ type: 'Array',
+ required: true,
+ description: 'The array of tokens to render',
+ },
+ {
+ name: 'onTokenRemove',
+ type: '(tokenId: string|number) => void',
+ required: true,
+ description: 'The function that gets called when a token is removed',
+ },
+ {
+ name: 'tokenComponent',
+ type: 'React.ComponentType',
+ defaultValue: 'Token',
+ description: 'The component used to render each token',
+ required: false,
+ },
+ {
+ name: 'maxHeight',
+ type: "React.CSSProperties['maxHeight']",
+ description:
+ 'The maximum height of the component. If the content in the input exceeds this height, it will scroll vertically',
+ required: false,
+ },
+ {
+ name: 'preventTokenWrapping',
+ type: 'boolean',
+ defaultValue: 'false',
+ description: 'Whether tokens should render inline horizontally. By default, tokens wrap to new lines',
+ required: false,
+ },
+ {
+ name: 'size',
+ type: "'small' | 'medium' | 'large' | 'xlarge'",
+ defaultValue: 'xlarge',
+ description: 'The size of the tokens and text input',
+ required: false,
+ },
+ {
+ name: 'hideTokenRemoveButtons',
+ type: 'boolean',
+ defaultValue: 'false',
+ description: 'Whether the remove buttons should be rendered in the tokens',
+ required: false,
+ },
+ {
+ name: 'validationStatus',
+ type: "'error' | 'success'",
+ description: 'Style the input to match the status',
+ required: false,
+ },
+ {
+ name: 'visibleTokenCount',
+ type: 'number',
+ description: 'The number of tokens to display before truncating',
+ required: false,
+ },
+ ],
+ subcomponents: [],
+ passthrough: {element: 'TextInput', url: '/react/TextInput'},
+})
diff --git a/packages/react/src/Textarea/Textarea.docs.ts b/packages/react/src/Textarea/Textarea.docs.ts
new file mode 100644
index 00000000000..abb79608d63
--- /dev/null
+++ b/packages/react/src/Textarea/Textarea.docs.ts
@@ -0,0 +1,99 @@
+import {defineComponent} from '../docs/component'
+
+export default defineComponent({
+ id: 'textarea',
+ name: 'Textarea',
+ status: 'alpha',
+ a11yReviewed: '2025-01-08',
+ stories: [
+ 'components-textarea--default',
+ 'components-textarea-features--disabled',
+ 'components-textarea-features--with-caption',
+ 'components-textarea-features--visually-hidden-label',
+ 'components-textarea-features--error',
+ 'components-textarea-features--success',
+ 'components-textarea-features--block',
+ 'components-textarea-features--custom-height',
+ 'components-textarea-features--custom-width',
+ 'components-textarea-features--custom-resize-behavior',
+ ],
+ importPath: '@primer/react',
+ props: [
+ {
+ name: 'required',
+ type: 'boolean',
+ description: 'Indicates to the user and assistive technologies that the field value is required',
+ required: false,
+ },
+ {
+ name: 'cols',
+ type: 'number',
+ defaultValue: '',
+ description: 'Specifies the visible width of a text area.',
+ required: false,
+ },
+ {
+ name: 'rows',
+ type: 'number',
+ defaultValue: '',
+ description: 'Specifies the visible height of a text area.',
+ required: false,
+ },
+ {
+ name: 'block',
+ type: 'boolean',
+ defaultValue: 'false',
+ description: 'Expands with width of the component to fill the parent elements',
+ required: false,
+ },
+ {
+ name: 'resize',
+ type: "'both' | 'horizontal' | 'vertical' | 'none'",
+ defaultValue: "'both'",
+ description: 'Changes the resize behavior',
+ required: false,
+ },
+ {
+ name: 'autoSize',
+ type: 'boolean',
+ defaultValue: 'false',
+ description: 'Allows the textarea to grow to fit its content',
+ required: false,
+ },
+ {
+ name: 'characterLimit',
+ type: 'number',
+ description: 'The maximum number of characters allowed in the textarea',
+ required: false,
+ },
+ {
+ name: 'contrast',
+ type: 'boolean',
+ defaultValue: 'false',
+ deprecated: true,
+ description: 'Deprecated. Omit this prop to use the default background.',
+ required: false,
+ },
+ {
+ name: 'validationStatus',
+ type: "'success' | 'error' | undefined",
+ description: 'Style the textarea to match the current form validation status',
+ required: false,
+ },
+ {
+ name: 'ref',
+ type: 'React.RefObject',
+ description: 'Ref to the rendered `