{ "schemaVersion": 2, "components": { "actionbar": { "source": "https://github.com/primer/react/tree/main/packages/react/src/ActionBar", "id": "actionbar", "name": "ActionBar", "status": "alpha", "a11yReviewed": "2025-01-08", "stories": [ { "id": "experimental-components-actionbar--default", "code": "() => (\n \n \n \n \n \n \n \n \n \n \n \n alert('Task List clicked')}\n >\n \n)" } ], "importPath": "@primer/react", "props": [ { "name": "aria-label", "type": "string", "required": false, "description": "When provided, a label is added to the action bar" }, { "name": "aria-labelledby", "type": "string", "required": false, "description": "When provided, uses the element with that ID as the accessible name for the ActionBar" }, { "name": "children", "type": "ReactNode", "required": false, "description": "Buttons in the action bar", "defaultValue": "" }, { "name": "size", "type": "'small' | 'large' | 'medium'", "required": false, "defaultValue": "'medium'", "description": "Size of the action bar" }, { "name": "flush", "type": "boolean", "required": false, "defaultValue": "false", "description": "Allows ActionBar to be flush with the container" }, { "name": "className", "type": "string", "required": false, "description": "Custom className", "defaultValue": "" }, { "name": "gap", "type": "'none' | 'condensed'", "required": false, "defaultValue": "'condensed'", "description": "Horizontal gap scale between items (restricted to none or condensed)." } ], "subcomponents": [ { "name": "ActionBar.IconButton", "props": [ { "name": "children", "type": "React.ReactNode", "defaultValue": "", "required": true, "description": "This will be the Button description." }, { "name": "icon", "type": "Component", "defaultValue": "", "description": "Provide an octicon. It will be placed in the center of the button" }, { "name": "aria-label", "type": "string", "defaultValue": "", "description": "Use an aria label to describe the functionality of the button. Please refer to [our guidance on alt text](https://primer.style/guides/accessibility/alternative-text-for-images) for tips on writing good alternative text." }, { "name": "disabled", "type": "boolean", "defaultValue": "", "description": "Provides a disabled state for the button. The button will remain focusable, and have `aria-disabled` applied." } ], "passthrough": { "element": "IconButton", "url": "/react/IconButton" } }, { "name": "ActionBar.Divider", "props": [] }, { "name": "ActionBar.Group", "props": [ { "name": "children", "type": "React.ReactNode", "defaultValue": "" } ] }, { "name": "ActionBar.Menu", "props": [ { "name": "aria-label", "type": "string", "required": true, "description": "Accessible label for the menu button." }, { "name": "icon", "type": "Component", "required": true, "description": "Icon for the menu button." }, { "name": "items", "type": "ActionBarMenuItemProps[]", "required": true, "description": "Array of menu items to render in the menu. Each item can be an action, group, or divider." }, { "name": "overflowIcon", "type": "Component | 'none'", "required": false, "description": "Icon displayed when the menu item is within the overflow menu. If 'none' is provided, no icon will be shown in the overflow menu." }, { "name": "returnFocusRef", "type": "React.RefObject", "required": false, "description": "A ref to an element that should receive focus when the menu is closed." } ] } ] }, "action_list": { "source": "https://github.com/primer/react/tree/main/packages/react/src/ActionList", "id": "action_list", "name": "ActionList", "status": "beta", "a11yReviewed": "2025-01-08", "stories": [ { "id": "components-actionlist--default", "code": "() => (\n \n Copy link\n Quote reply\n Edit comment\n \n)" }, { "id": "components-actionlist-features--simple-list", "code": "() => (\n \n Copy link\n Quote reply\n Edit comment\n \n Delete file\n \n)" }, { "id": "components-actionlist-features--with-visual-list-heading", "code": "() => (\n \n \n Filter by\n \n \n Repositories\n {}}>\n \n \n \n app/assets/modules\n \n {}}>\n \n \n \n src/react/components\n \n {}}>\n \n \n \n memex/shared-ui/components\n \n {}}>\n \n \n \n views/assets/modules\n \n \n\n \n Advanced\n {}}>\n \n \n \n Owner\n \n {}}>\n \n \n \n Symbol\n \n {}}>\n \n \n \n Exclude archived\n \n \n \n)" }, { "id": "components-actionlist-features--with-custom-heading", "code": "() => (\n <>\n \n Details\n \n \n \n \n \n \n Readme\n \n \n \n \n \n MIT License\n \n \n \n \n \n 1.5k stars\n \n \n \n \n \n 21 watching\n \n \n \n \n \n 225 forks\n \n \n \n)" }, { "id": "components-actionlist-features--with-icons", "code": "() => (\n \n \n \n \n \n github.com/primer\n \n \n \n \n \n MIT License\n \n \n \n \n \n 256 stars\n \n \n \n \n \n 3 forks\n \n \n \n \n \n 4 vulnerabilities\n \n \n)" }, { "id": "components-actionlist-features--with-avatars", "code": "() => (\n \n {users.map((user) => (\n \n \n \n \n {user.login}\n \n ))}\n \n)" }, { "id": "components-actionlist-features--item-dividers", "code": "() => (\n \n Copy link\n Quote reply\n Edit comment\n \n)" }, { "id": "components-actionlist-features--single-divider", "code": "() => (\n \n Copy link\n Quote reply\n Edit comment\n \n Delete file\n \n)" }, { "id": "components-actionlist-features--inline-description", "code": "() => (\n \n {users.map((user) => (\n \n \n \n \n {user.login}\n {user.name}\n \n ))}\n \n)" }, { "id": "components-actionlist-features--block-description", "code": "() => (\n \n {users.map((user) => (\n \n \n \n \n {user.login}\n \n {user.name}\n \n \n ))}\n \n)" }, { "id": "components-actionlist-features--single-select", "code": "() => {\n const [selectedIndex, setSelectedIndex] = React.useState(0)\n return (\n \n {projects.map((project, index) => (\n setSelectedIndex(index)}\n >\n \n \n \n {project.name}\n \n {project.scope}\n \n \n ))}\n \n )\n}" }, { "id": "components-actionlist-features--inactive-single-select", "code": "() => {\n const [selectedIndex, setSelectedIndex] = React.useState(1)\n return (\n \n {/* menuitem because state is inactive */}\n \n Inactive item\n \n setSelectedIndex(1)}\n >\n Item 2\n \n \n )\n}" }, { "id": "components-actionlist-features--multi-select", "code": "() => {\n const [selectedIndices, setSelectedIndices] = React.useState([0])\n const handleSelect = (index: number) => {\n if (selectedIndices.includes(index)) {\n setSelectedIndices(selectedIndices.filter((i) => i !== index))\n } else {\n setSelectedIndices([...selectedIndices, index])\n }\n }\n return (\n \n {projects.map((project, index) => (\n handleSelect(index)}\n disabled={index === 3 ? true : undefined}\n >\n \n \n \n {project.name}\n \n {project.scope}\n \n \n ))}\n \n )\n}" }, { "id": "components-actionlist-features--listbox-single-select", "code": "() => {\n const [selectedIndice, setSelectedIndice] = React.useState(0)\n const handleSelect = (index: number) => {\n setSelectedIndice(index)\n }\n return (\n \n {projects.map((project, index) => (\n handleSelect(index)}\n disabled={index === 3 ? true : undefined}\n role=\"option\"\n >\n \n \n \n {project.name}\n \n {project.scope}\n \n \n ))}\n \n )\n}" }, { "id": "components-actionlist-features--listbox-multi-select", "code": "() => {\n const [selectedIndices, setSelectedIndices] = React.useState([0])\n const handleSelect = (index: number) => {\n if (selectedIndices.includes(index)) {\n setSelectedIndices(selectedIndices.filter((i) => i !== index))\n } else {\n setSelectedIndices([...selectedIndices, index])\n }\n }\n return (\n \n {projects.map((project, index) => (\n handleSelect(index)}\n disabled={index === 3 ? true : undefined}\n >\n \n \n \n {project.name}\n \n {project.scope}\n \n \n ))}\n \n )\n}" }, { "id": "components-actionlist-features--with-dynamic-content", "code": "() => {\n const [isTrue, setIsTrue] = React.useState(false)\n return (\n \n {\n setIsTrue(!isTrue)\n }}\n >\n Activated? {isTrue ? 'Yes' : 'No'}\n \n \n )\n}" }, { "id": "components-actionlist-features--disabled-selected-multiselect", "code": "() => (\n \n \n Selected disabled item\n \n \n Item 2\n \n \n)" }, { "id": "components-actionlist-features--disabled-multiselect", "code": "() => (\n \n \n Disabled item\n \n \n Item 2\n \n \n)" }, { "id": "components-actionlist-features--inactive-multiselect", "code": "() => {\n const [selectedIndices, setSelectedIndices] = React.useState([0])\n const handleSelect = (index: number) => {\n if (selectedIndices.includes(index)) {\n setSelectedIndices(selectedIndices.filter((i) => i !== index))\n } else {\n setSelectedIndices([...selectedIndices, index])\n }\n }\n return (\n \n {/* menuitem because state is inactive */}\n \n Inactive item\n \n handleSelect(1)}\n >\n Item 2\n \n \n )\n}" }, { "id": "components-actionlist-features--disabled-item", "code": "() => {\n const [selectedIndex, setSelectedIndex] = React.useState(0)\n return (\n \n {projects.map((project, index) => (\n setSelectedIndex(index)}\n disabled={index === 1}\n >\n \n \n \n {project.name}\n \n {project.scope}\n \n \n ))}\n \n )\n}" }, { "id": "components-actionlist-features--inactive-item", "code": "() => {\n return (\n \n {projects.map((project, index) => (\n \n \n \n \n {project.name}\n \n {project.scope}\n \n \n ))}\n \n )\n}" }, { "id": "components-actionlist-features--loading-item", "code": "() => {\n return (\n \n {projects.map((project, index) => (\n \n {project.name}\n \n {project.scope}\n \n \n ))}\n \n )\n}" }, { "id": "components-actionlist-features--links", "code": "() => (\n \n \n Details\n \n \n \n \n \n Readme\n \n \n \n \n \n MIT License\n \n \n \n \n \n 1.5k stars\n \n \n \n \n \n 21 watching\n \n \n \n \n \n 225 forks\n \n \n)" }, { "id": "components-actionlist-features--custom-item-children", "code": "() => (\n \n \n \n \n \n \n \n \n \n \n \n)" }, { "id": "components-actionlist-features--text-wrap-and-truncation", "code": "() => (\n
\n \n \n \n \n \n Block Description. Long text should wrap\n \n This description is long, but it is block so it wraps\n \n \n \n \n \n \n \n \n \n Inline Description\n \n This description gets truncated because it is inline with truncation\n \n \n \n \n \n \n \n \n \n Description with truncation and complex children\n \n With bold and italic text, and it should\n truncate if it is too long\n \n \n \n \n \n \n \n \n \n Inline Description\n \n This description wraps because it is inline without truncation\n \n \n \n \n \n \n \n \n \n Really long text without a description should wrap so it wraps\n \n \n \n \n \n \n \n \n SomethingSomething/SomethingElse.Some.Thing.Lalala.la\n \n \n \n \n \n
\n)" }, { "id": "components-actionlist-features--conditional-children", "code": "() => {\n type reviewerType = {\n name: string\n id?: string\n type?: string\n login?: string\n slug?: string\n members?: number\n }\n const potentialReviewers: reviewerType[] = [...teams, ...users]\n return (\n \n {potentialReviewers.map((reviewer, index) => (\n \n \n {reviewer.type === 'team' ? (\n \n ) : (\n \n )}\n \n {reviewer.login || reviewer.slug}\n {reviewer.type === 'team' ? (\n \n {reviewer.name}\n \n ) : (\n {reviewer.name}\n )}\n {reviewer.type === 'team' && (\n \n \n {reviewer.members}\n \n )}\n \n ))}\n \n )\n}" }, { "id": "components-actionlist-features--child-with-side-effects", "code": "() => {\n const user = users[0]\n const [selected, setSelected] = React.useState(true)\n return (\n \n setSelected(!selected)}\n role=\"option\"\n >\n \n \n \n {user.login}\n \n \n \n \n \n )\n}" }, { "id": "components-actionlist-features--inside-overlay", "code": "() => {\n const [open, setOpen] = React.useState(false)\n const toggle = () => setOpen(!open)\n return (\n (\n \n )}\n >\n \n \n Use your arrow keys\n ↓\n \n \n keep going\n ↓\n \n \n more more\n ↓\n \n \n \n now go up!\n ↑\n \n \n \n )\n}" }, { "id": "components-actionlist-features--group-with-subtle-title", "code": "() => {\n const [assignees, setAssignees] = React.useState(users.slice(0, 1))\n const toggleAssignee = (assignee: (typeof users)[number]) => {\n const assigneeIndex = assignees.findIndex((a) => a.login === assignee.login)\n if (assigneeIndex === -1) setAssignees([...assignees, assignee])\n else setAssignees(assignees.filter((_, index) => index !== assigneeIndex))\n }\n return (\n \n \n Everyone\n {users.slice(2).map((user) => (\n assignee.login === user.login),\n )}\n aria-checked={Boolean(\n assignees.find((assignee) => assignee.login === user.login),\n )}\n onSelect={() => toggleAssignee(user)}\n >\n \n \n \n {user.login}\n {user.name}\n \n ))}\n \n \n )\n}" }, { "id": "components-actionlist-features--group-with-filled-title", "code": "() => {\n const [assignees, setAssignees] = React.useState(users.slice(0, 1))\n const toggleAssignee = (assignee: (typeof users)[number]) => {\n const assigneeIndex = assignees.findIndex((a) => a.login === assignee.login)\n if (assigneeIndex === -1) setAssignees([...assignees, assignee])\n else setAssignees(assignees.filter((_, index) => index !== assigneeIndex))\n }\n return (\n \n \n \n Everyone\n \n {users.slice(2).map((user) => (\n assignee.login === user.login),\n )}\n aria-checked={Boolean(\n assignees.find((assignee) => assignee.login === user.login),\n )}\n onSelect={() => toggleAssignee(user)}\n >\n \n \n \n {user.login}\n {user.name}\n \n ))}\n \n \n )\n}" }, { "id": "components-actionlist-features--with-custom-trailing-visuals", "code": "() => (\n \n \n \n \n \n Issues\n \n 20\n \n \n \n \n \n \n PRs\n \n 12\n \n \n \n \n \n \n Projects\n \n 2\n \n \n \n)" }, { "id": "components-actionlist-features--with-keyboard-shortcuts", "code": "() => (\n \n \n New file\n \n \n \n \n \n Open file\n \n \n \n \n \n Save\n \n \n \n \n \n \n Delete\n \n \n \n \n \n)" }, { "id": "components-actionlist-features--with-trailing-count", "code": "() => (\n \n \n \n \n \n Open issues\n \n 24\n \n \n \n \n \n \n Pull requests\n \n 8\n \n \n \n \n \n \n Projects\n \n 3\n \n \n \n \n \n \n Alerts\n \n 12\n \n \n \n)" }, { "id": "components-actionlist-features--with-trailing-action", "code": "() => {\n const [loadingState, setLoadingState] = React.useState(false)\n\n // Auto-toggle every 2.5 seconds to continuously show transitions\n React.useEffect(() => {\n const interval = setInterval(() => {\n setLoadingState((prev) => !prev)\n }, 2500)\n return () => clearInterval(interval)\n }, [])\n return (\n \n \n \n \n \n Item 1 (with default TrailingAction)\n \n \n \n Item 2 (with link TrailingAction)\n \n \n \n Item 3\n \n This is an inline description.\n \n \n \n \n Item 4\n \n This is a block description.\n \n \n \n \n Item 5\n \n This is a block description.\n \n \n \n \n Item 6\n \n \n \n Icon button loading state\n \n Shows how IconButton maintains width and centers spinner when loading\n \n \n \n \n Icon button with transitions\n \n Automatically toggles loading state every 2.5 seconds to show\n transitions\n \n \n \n \n Text button loading state\n \n Shows how text button aligns spinner to the right and preserves width\n \n \n \n \n Text button with transitions\n \n Automatically toggles loading state every 2.5 seconds to show\n transitions\n \n \n \n \n LinkItem 1\n \n with TrailingAction this is a long description and should not cause\n horizontal scroll on smaller screen sizes\n \n \n \n \n LinkItem 2\n \n with TrailingVisual this is a long description and should not cause\n horizontal scroll on smaller screen sizes\n \n \n \n \n \n \n Inactive Item\n With TrailingAction\n \n \n \n )\n}" }, { "id": "components-actionlist-features--with-trailing-action-on-group-heading", "code": "() => (\n \n \n \n \n Custom fields\n \n \n \n \n \n \n Field 1\n \n \n \n \n \n Field 2\n \n \n \n \n Repositories\n \n \n primer/react\n primer/primitives\n \n \n \n)" }, { "id": "components-actionlist-features--full-variant", "code": "() => (\n \n Copy link\n Quote reply\n Edit comment\n \n Delete file\n \n)" }, { "id": "components-actionlist-features--large-item", "code": "() => (\n \n Large item\n \n Large item\n With inline description\n \n \n Large item\n \n With block description\n \n \n \n)" } ], "importPath": "@primer/react", "props": [ { "name": "children", "type": "ActionList.Item[] | ActionList.LinkItem[] | ActionList.Group[]", "defaultValue": "", "required": true, "description": "" }, { "name": "variant", "type": "'inset' | 'horizontal-inset' | 'full'", "defaultValue": "'inset'", "description": "`inset` children are offset (vertically and/or horizontally) from list edges. `full` children are flush (vertically and horizontally) with list edges" }, { "name": "selectionVariant", "type": "'single' | 'multiple'", "defaultValue": "", "description": "Whether multiple items or a single item can be selected." }, { "name": "showDividers", "type": "boolean", "description": "Display a divider above each `Item` in this `List` when it does not follow a `Header` or `Divider`.", "defaultValue": "" }, { "name": "role", "type": "AriaRole", "defaultValue": "", "description": "ARIA role describing the function of the list. `listbox` and `menu` are a common values." } ], "subcomponents": [ { "name": "ActionList.Item", "props": [ { "name": "children", "type": "React.ReactNode | ActionList.LeadingVisual | ActionList.Description | ActionList.TrailingVisual", "defaultValue": "", "required": true, "description": "Primary content for an Item" }, { "name": "variant", "type": "'default' | 'danger'", "defaultValue": "'default'", "description": "`danger` indicates that the item is destructive." }, { "name": "size", "type": "'medium' | 'large'", "defaultValue": "'medium'", "description": "The block size of the ActionList items." }, { "name": "onSelect", "type": "(event: React.MouseEvent | React.KeyboardEvent) => void", "defaultValue": "", "description": "Callback that is called when the item is selected using either the mouse or keyboard. `event.preventDefault()` will prevent a menu from closing when within an ``. This is not called for disabled or inactive items." }, { "name": "selected", "type": "boolean", "defaultValue": "false", "description": "Indicate whether the item is selected. Only applies to items that can be selected." }, { "name": "active", "type": "boolean", "defaultValue": "false", "description": "Indicate whether the item is active. There should never be more than one active item." }, { "name": "disabled", "type": "boolean", "defaultValue": "false", "description": "Items that are disabled can not be clicked, selected, or navigated to." }, { "name": "inactiveText", "type": "string", "defaultValue": "", "description": "Text describing why the item is inactive. This may be used when an item's usual functionality is unavailable due to a system error such as a database outage.\nIf there is a leading visual, the alert icon will replace the leading visual.\nIf there is a trailing visual, it will replace the trailing visual.\nIf there is no visual passed, it will be shown in the trailing visual slot to preserve left alignment of item content.\nText will appear in a tooltip triggered by the alert icon in ActionList items, but text will appear below the description or title on ActionMenu items." }, { "name": "loading", "type": "boolean", "description": "Whether the item is loading." }, { "name": "role", "type": "AriaRole", "defaultValue": "", "description": "ARIA role describing the function of the item. `option` is a common value." }, { "name": "id", "type": "string", "required": false, "description": "id to attach to the root element of the Item", "defaultValue": "" } ] }, { "name": "ActionList.Heading", "props": [ { "name": "children", "type": "React.ReactNode", "defaultValue": "", "required": true, "description": "Use to give a heading to list" }, { "name": "as", "type": "h1 | h2 | h3 | h4 | h5 | h6", "defaultValue": "h3", "required": false, "description": "The level of the heading" }, { "name": "visuallyHidden", "type": "boolean", "required": false, "description": "", "defaultValue": "" } ] }, { "name": "ActionList.LinkItem", "props": [ { "name": "children", "type": "React.ReactNode | ActionList.LeadingVisual | ActionList.Description | ActionList.TrailingVisual", "defaultValue": "", "required": true, "description": "" }, { "name": "active", "type": "boolean", "defaultValue": "false", "description": "Indicate whether the item is active. There should never be more than one active item." }, { "name": "ref", "type": "React.RefObject" }, { "name": "as", "type": "React.ElementType", "defaultValue": "\"a\"" }, { "name": "inactiveText", "type": "string", "required": false, "description": "Text describing why the item is inactive. This may be used when an item's usual functionality\nis unavailable due to a system error such as a database outage.", "defaultValue": "" } ], "passthrough": { "element": "a", "url": "https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#Attributes" } }, { "name": "ActionList.LeadingVisual", "props": [ { "name": "children", "type": "React.ReactNode", "defaultValue": "", "required": true, "description": "Icon (or similar) positioned before item text." } ] }, { "name": "ActionList.TrailingVisual", "props": [ { "name": "children", "type": "React.ReactNode", "defaultValue": "", "required": true, "description": "Visual positioned after item text." } ] }, { "name": "ActionList.TrailingAction", "props": [ { "name": "as", "type": "a | button", "defaultValue": "button", "required": false, "description": "HTML element to render as." }, { "name": "label", "type": "string", "defaultValue": "", "required": true, "description": "Accessible name for the control." }, { "name": "icon", "type": "string", "defaultValue": "", "required": true, "description": "Octicon to pass into IconButton. When this is not set, TrailingAction renders as a `Button` instead of an `IconButton`." }, { "name": "href", "type": "string", "description": "href when the TrailingAction is rendered as a link." }, { "name": "loading", "type": "boolean", "defaultValue": "false", "description": "Whether the TrailingAction is in a loading state. When true, the TrailingAction will render a spinner instead of an icon. Only available when `as` is 'button'." } ] }, { "name": "ActionList.Description", "props": [ { "name": "children", "type": "React.ReactNode", "defaultValue": "", "required": true, "description": "" }, { "name": "variant", "type": "'inline' | 'block'", "defaultValue": "'inline'", "description": "`inline` descriptions are positioned beside primary text. `block` descriptions are positioned below primary text." }, { "name": "className", "type": "string | undefined", "defaultValue": "", "description": "CSS string" }, { "name": "truncate", "type": "boolean", "defaultValue": "false", "description": "Whether the inline description should truncate the text on overflow." } ] }, { "name": "ActionList.GroupHeading", "props": [ { "name": "children", "type": "React.ReactNode", "defaultValue": "", "required": true, "description": "Use to give a heading to the groups" }, { "name": "variant", "type": "'filled' | 'subtle'", "defaultValue": "'subtle'", "description": "`filled` style has a background color and top and bottom borders. Subtle style has no background or borders." }, { "name": "auxiliaryText", "type": "string", "required": false, "description": "Secondary text which provides additional information about a `Group`.", "defaultValue": "" }, { "name": "visuallyHidden", "type": "boolean", "required": false, "description": "", "defaultValue": "" }, { "name": "as", "type": "h1 | h2 | h3 | h4 | h5 | h6", "defaultValue": "h3", "required": false, "description": "The level of the heading and it is only required (enforce by runtime warning) for lists. (i.e. not required for ActionMenu or listbox roles)" } ] }, { "name": "ActionList.Group", "props": [ { "name": "children", "type": "ActionList.Item[] | ActionList.LinkItem[]", "defaultValue": "", "required": true, "description": "" }, { "name": "title", "type": "string", "defaultValue": "", "description": "Please use `ActionList.GroupHeading` instead.", "deprecated": true }, { "name": "auxiliaryText", "type": "string", "defaultValue": "", "description": "Secondary text that provides additional information about the group." }, { "name": "variant", "type": "'filled' | 'subtle'", "defaultValue": "'subtle'", "description": "`inline` descriptions are positioned beside primary text. `block` descriptions are positioned below primary text." }, { "name": "selectionVariant", "type": "'single' | 'multiple' | false", "defaultValue": "", "description": "Set `selectionVariant` at the group level." }, { "name": "role", "type": "AriaRole", "defaultValue": "", "description": "ARIA role describing the function of the list inside the group. `listbox` and `menu` are a common values." } ] } ] }, "action_menu": { "source": "https://github.com/primer/react/tree/main/packages/react/src/ActionMenu", "id": "action_menu", "name": "ActionMenu", "status": "beta", "a11yReviewed": "2025-01-08", "stories": [ { "id": "components-actionmenu--default", "code": "() => (\n \n Open menu\n \n \n alert('Copy link clicked')}>\n Copy link\n ⌘C\n \n alert('Quote reply clicked')}>\n Quote reply\n ⌘Q\n \n alert('Edit comment clicked')}>\n Edit comment\n ⌘E\n \n \n alert('Delete file clicked')}\n >\n Delete file\n ⌘D\n \n \n \n \n)" }, { "id": "components-actionmenu-features--links-and-actions", "code": "() => (\n \n Open menu\n \n \n alert('Workflows clicked')}>\n Workflows\n \n \n \n \n alert('Archived items clicked')}>\n Archived items\n \n \n \n \n \n Settings\n \n \n \n \n alert('Make a copy clicked')}>\n Make a copy\n \n \n \n \n \n \n GitHub projects\n \n What's new\n \n \n \n \n \n Give feedback\n \n \n \n \n \n GitHub Docs\n \n \n \n \n \n \n \n \n)" }, { "id": "components-actionmenu-features--single-select", "code": "() => {\n const options = [\n {\n name: 'Fast forward',\n },\n {\n name: 'Recursive',\n },\n {\n name: 'Ours',\n },\n {\n name: 'Octopus',\n },\n {\n name: 'Resolve',\n },\n {\n name: 'Subtree',\n },\n ]\n const [selectedIndex, setSelectedIndex] = React.useState(0)\n const selectedType = options[selectedIndex]\n return (\n \n \n Options: {selectedType.name}\n \n \n \n {options.map((options, index) => (\n setSelectedIndex(index)}\n >\n {options.name}\n \n ))}\n \n \n \n )\n}" }, { "id": "components-actionmenu-features--multi-select", "code": "() => {\n type Option = {\n name: string\n selected: boolean\n }\n const [options, setOptions] = React.useState([\n {\n name: 'Show code folding buttons',\n selected: true,\n },\n {\n name: 'Wrap lines',\n selected: false,\n },\n {\n name: 'Center content',\n selected: false,\n },\n ])\n const toggle = (name: string) => {\n setOptions(\n options.map((option) => {\n if (option.name === name) option.selected = !option.selected\n return option\n }),\n )\n }\n return (\n \n Display\n \n \n {options.map((options) => (\n toggle(options.name)}\n >\n {options.name}\n \n ))}\n \n \n \n )\n}" }, { "id": "components-actionmenu-features--inactive-items", "code": "() => (\n \n Open menu\n \n \n alert('Workflows clicked')}\n inactiveText=\"Unavailable due to an outage\"\n >\n Workflows\n \n \n \n \n alert('Archived items clicked')}\n inactiveText=\"Unavailable due to an outage\"\n >\n Archived items\n \n \n \n \n \n Settings\n \n \n \n \n alert('Make a copy clicked')}\n inactiveText=\"Unavailable due to an outage\"\n >\n Make a copy\n \n \n \n \n \n \n Github projects\n \n What's new\n \n \n \n \n \n Give feedback\n \n \n \n \n \n GitHub Docs\n \n \n \n \n \n \n \n \n)" }, { "id": "components-actionmenu-features--loading-items", "code": "() => (\n \n Open menu\n \n \n alert('Workflows clicked')} loading>\n Workflows\n \n \n \n \n alert('Archived items clicked')}\n loading\n >\n Archived items\n \n \n \n \n alert('Make a copy clicked')} loading>\n Make a copy\n \n \n \n \n \n \n Github projects\n \n What's new\n \n \n \n \n \n Give feedback\n \n \n \n \n \n GitHub Docs\n \n \n \n \n \n \n \n \n)" }, { "id": "components-actionmenu-features--submenus", "code": "() => (\n \n Edit\n \n \n Cut\n Copy\n Paste\n \n \n \n \n \n \n Paste special\n \n \n \n \n Paste plain text\n Paste formulas\n Paste with formatting\n \n \n Paste from\n \n \n \n Current clipboard\n History\n Another device\n \n \n \n \n \n \n \n \n \n)" } ], "importPath": "@primer/react", "props": [ { "name": "children", "type": "React.ReactElement[]", "defaultValue": "", "required": true, "description": "Recommended: `ActionMenu.Button` or `ActionMenu.Anchor` with `ActionMenu.Overlay`" }, { "name": "open", "type": "boolean", "defaultValue": "false", "description": "If defined, will control the open/closed state of the overlay. Must be used in conjuction with `onOpenChange`." }, { "name": "onOpenChange", "type": "(open: boolean) => void", "defaultValue": "", "description": "If defined, will control the open/closed state of the overlay. Must be used in conjuction with `open`." }, { "name": "anchorRef", "type": "React.RefObject", "defaultValue": "", "description": "Useful for defining an external anchor" } ], "subcomponents": [ { "name": "ActionMenu.Button", "props": [ { "name": "children", "type": "React.ReactElement", "defaultValue": "", "required": true, "description": "" } ], "passthrough": { "element": "Button", "url": "/react/Button" } }, { "name": "ActionMenu.Anchor", "props": [ { "name": "children", "type": "React.ReactElement", "defaultValue": "", "required": true, "description": "Accepts a single child element" }, { "name": "id", "type": "string", "description": "", "defaultValue": "" } ] }, { "name": "ActionMenu.Overlay", "props": [ { "name": "children", "type": "React.ReactNode", "defaultValue": "", "required": true, "description": "" }, { "name": "align", "type": "start | center | end", "defaultValue": "start", "description": "" }, { "name": "side", "type": "| 'inside-top' | 'inside-bottom' | 'inside-left' | 'inside-right' | 'inside-center' | 'outside-top' | 'outside-bottom' | 'outside-left' | 'outside-right'", "defaultValue": "'outside-bottom'", "description": "Controls which side of the anchor the menu will appear" }, { "name": "onPositionChange", "type": "({ position }: { position: AnchorPosition }) => void", "defaultValue": "", "description": "Callback that is called when the position of the overlay changes" }, { "name": "data-test-id", "type": "unknown", "required": false, "description": "ID to use for React testing utilities.", "defaultValue": "" } ], "passthrough": { "element": "Overlay", "url": "/react/Overlay" } } ] }, "anchored_overlay": { "source": "https://github.com/primer/react/tree/main/packages/react/src/AnchoredOverlay", "id": "anchored_overlay", "name": "AnchoredOverlay", "status": "alpha", "a11yReviewed": "2025-01-08", "stories": [ { "id": "components-anchoredoverlay--default", "code": "() => {\n const [open, setOpen] = useState(false)\n return (\n setOpen(true)}\n onClose={() => setOpen(false)}\n renderAnchor={(props) => }\n overlayProps={{\n role: 'dialog',\n 'aria-modal': true,\n 'aria-label': 'User Card Overlay',\n style: {\n minWidth: '320px',\n },\n }}\n focusZoneSettings={{\n disabled: true,\n }}\n preventOverflow={false}\n >\n {hoverCard}\n \n )\n}" }, { "id": "components-anchoredoverlay-features--portal-inside-scrolling-element", "code": "(args: Args) => {\n const rows = 20\n const columns = 10\n return (\n \n \n \n {Array(rows)\n .fill(null)\n .map((_, i) => (\n \n {Array(columns)\n .fill(null)\n .map((_1, j) => (\n \n ))}\n \n ))}\n \n
\n
\n \n
\n
\n \n )\n}" }, { "id": "components-anchoredoverlay-features--custom-anchor-id", "code": "() => {\n const [open, setOpen] = useState(false)\n return (\n setOpen(true)}\n onClose={() => setOpen(false)}\n renderAnchor={(props) => }\n anchorId=\"my-custom-anchor-id\"\n overlayProps={{\n role: 'dialog',\n 'aria-modal': true,\n 'aria-label': 'User Card Overlay',\n className: classes.Overlay,\n }}\n focusZoneSettings={{\n disabled: true,\n }}\n preventOverflow={false}\n >\n
{hoverCard}
\n \n )\n}" }, { "id": "components-anchoredoverlay-features--height", "code": "() => {\n const [open, setOpen] = useState(false)\n return (\n setOpen(true)}\n onClose={() => setOpen(false)}\n renderAnchor={(props) => }\n height=\"large\"\n overlayProps={{\n role: 'dialog',\n 'aria-modal': true,\n 'aria-label': 'User Card Overlay',\n className: classes.Overlay,\n }}\n focusZoneSettings={{\n disabled: true,\n }}\n preventOverflow={false}\n >\n
{hoverCard}
\n \n )\n}" }, { "id": "components-anchoredoverlay-features--width", "code": "() => {\n const [open, setOpen] = useState(false)\n return (\n setOpen(true)}\n onClose={() => setOpen(false)}\n renderAnchor={(props) => }\n width=\"large\"\n overlayProps={{\n role: 'dialog',\n 'aria-modal': true,\n 'aria-label': 'User Card Overlay',\n className: classes.Overlay,\n }}\n focusZoneSettings={{\n disabled: true,\n }}\n preventOverflow={false}\n >\n
{hoverCard}
\n \n )\n}" }, { "id": "components-anchoredoverlay-features--anchor-alignment", "code": "() => {\n const [open, setOpen] = useState(false)\n return (\n setOpen(true)}\n onClose={() => setOpen(false)}\n renderAnchor={(props) => (\n \n )}\n align=\"center\"\n overlayProps={{\n role: 'dialog',\n 'aria-modal': true,\n 'aria-label': 'User Card Overlay',\n className: classes.Overlay,\n }}\n focusZoneSettings={{\n disabled: true,\n }}\n preventOverflow={false}\n >\n
{hoverCard}
\n \n )\n}" }, { "id": "components-anchoredoverlay-features--anchor-side", "code": "() => {\n const [open, setOpen] = useState(false)\n return (\n setOpen(true)}\n onClose={() => setOpen(false)}\n renderAnchor={(props) => }\n side=\"outside-right\"\n overlayProps={{\n role: 'dialog',\n 'aria-modal': true,\n 'aria-label': 'User Card Overlay',\n className: classes.Overlay,\n }}\n focusZoneSettings={{\n disabled: true,\n }}\n preventOverflow={false}\n >\n
{hoverCard}
\n \n )\n}" }, { "id": "components-anchoredoverlay-features--offset-position-from-anchor", "code": "() => {\n const [open, setOpen] = useState(false)\n return (\n setOpen(true)}\n onClose={() => setOpen(false)}\n renderAnchor={(props) => }\n anchorOffset={100}\n overlayProps={{\n role: 'dialog',\n 'aria-modal': true,\n 'aria-label': 'User Card Overlay',\n className: classes.Overlay,\n }}\n focusZoneSettings={{\n disabled: true,\n }}\n preventOverflow={false}\n >\n
{hoverCard}
\n \n )\n}" }, { "id": "components-anchoredoverlay-features--offset-alignment-from-anchor", "code": "() => {\n const [open, setOpen] = useState(false)\n return (\n setOpen(true)}\n onClose={() => setOpen(false)}\n renderAnchor={(props) => }\n alignmentOffset={100}\n overlayProps={{\n role: 'dialog',\n 'aria-modal': true,\n 'aria-label': 'User Card Overlay',\n className: classes.Overlay,\n }}\n focusZoneSettings={{\n disabled: true,\n }}\n preventOverflow={false}\n >\n
{hoverCard}
\n \n )\n}" }, { "id": "components-anchoredoverlay-features--focus-trap-overrides", "code": "() => {\n const initialFocusRef = useRef(null)\n const [open, setOpen] = useState(false)\n return (\n setOpen(true)}\n onClose={() => setOpen(false)}\n renderAnchor={(props) => }\n focusTrapSettings={{\n initialFocusRef,\n }}\n overlayProps={{\n role: 'dialog',\n 'aria-modal': true,\n 'aria-label': 'Focus Trap Demo Overlay',\n className: classes.Overlay,\n }}\n focusZoneSettings={{\n disabled: true,\n }}\n preventOverflow={false}\n >\n \n \n \n )\n}" }, { "id": "components-anchoredoverlay-features--focus-zone-overrides", "code": "() => {\n const [open, setOpen] = useState(false)\n return (\n setOpen(true)}\n onClose={() => setOpen(false)}\n renderAnchor={(props) => }\n focusZoneSettings={{\n bindKeys: FocusKeys.JK,\n }}\n overlayProps={{\n role: 'dialog',\n 'aria-modal': true,\n 'aria-label': 'Focus Zone Demo Overlay',\n className: classes.Overlay,\n }}\n preventOverflow={false}\n >\n

\n Use J and K keys to move focus.\n

\n \n \n \n \n )\n}" }, { "id": "components-anchoredoverlay-features--overlay-props-overrides", "code": "() => {\n const [open, setOpen] = useState(false)\n return (\n setOpen(true)}\n onClose={() => setOpen(false)}\n renderAnchor={(props) => }\n overlayProps={{\n overflow: 'auto',\n maxHeight: 'xsmall',\n role: 'dialog',\n 'aria-modal': true,\n 'aria-label': 'User Card Overlay',\n className: classes.Overlay,\n }}\n focusZoneSettings={{\n disabled: true,\n }}\n preventOverflow={false}\n >\n
Overlay props have been overridden to set:
\n 
\n        
  • overflow: `auto`
    • \n        
  • maxHeight: `xsmall`
    • \n
    \n
    {hoverCard}
    \n \n )\n}" } ], "importPath": "@primer/react", "props": [ { "name": "open", "type": "boolean", "required": true, "defaultValue": "false", "description": "Determines whether the overlay portion of the component should be shown or not." }, { "name": "onOpen", "type": "(gesture: 'anchor-click' | 'anchor-key-press', event?: KeyboardEvent | undefined) => unknown", "defaultValue": "", "description": "A callback that is called whenever the overlay is currently closed and an \"open gesture\" is detected." }, { "name": "onClose", "type": "(gesture: 'anchor-click' | 'click-outside' | 'escape') => unknown", "defaultValue": "", "description": "A callback that is called whenever the overlay is currently open and a \"close gesture\" is detected." }, { "name": "renderAnchor", "type": ">(props: T) => JSX.Element", "defaultValue": "", "description": "A custom function component used to render the anchor element. When renderAnchor is null, an anchorRef is required." }, { "name": "anchorRef", "type": "React.RefObject", "defaultValue": "", "description": "An override to the internal `renderAnchor` ref that will be used to position the overlay. When `renderAnchor` is `null`, this can be used to make an anchor that is detached from ` AnchoredOverlay `." }, { "name": "anchorId", "type": "string", "defaultValue": "", "description": "An override to the internal id that will be passed to the anchor." }, { "name": "side", "type": "| 'inside-top' | 'inside-bottom' | 'inside-left' | 'inside-right' | 'inside-center' | 'outside-top' | 'outside-bottom' | 'outside-left' | 'outside-right'", "defaultValue": "'outside-bottom'", "description": "" }, { "name": "align", "type": "'start' | 'center' | 'end'", "defaultValue": "'start'", "description": "" }, { "name": "alignmentOffset", "type": "number", "defaultValue": "4", "description": "An additional offset, in pixels, to move the floating element from the aligning edge. Positive values move the floating element in the direction of center-alignment. Negative values move the floating element away from center-alignment. When align is `'center`, positive offsets move the floating element right (top or bottom anchor side) or down (left or right anchor side). If using outside positioning, or if `align` is set to `'center'`, this defaults to `0` instead of `4`." }, { "name": "anchorOffset", "type": "number", "defaultValue": "4", "description": "The number of pixels between the anchor edge and the floating element. Positive values move the floating element farther from the anchor element (for outside positioning) or further inside the anchor element (for inside positioning). Negative values have the opposite effect. If `side` is set to `'inside-center'`, this defaults to `0` instead of `4`." }, { "name": "overlayProps", "type": "Partial", "defaultValue": "", "description": "Props to be spread on the internal `Overlay` component." }, { "name": "focusTrapSettings", "type": "Partial", "defaultValue": "", "description": "Settings to apply to the focus trap on the internal `Overlay` component." }, { "name": "focusZoneSettings", "type": "Partial", "defaultValue": "", "description": "Settings to apply to the focus zone on the internal `Overlay` component." }, { "name": "className", "type": "string", "defaultValue": "", "description": "Class name for custom styling." }, { "name": "preventOverflow", "type": "boolean", "defaultValue": "true", "description": "Determines if the Overlay width should be adjusted responsively if there is not enough space to display the Overlay. If `preventOverflow` is set to `false`, the Overlay will be displayed at the maximum width that fits within the viewport." }, { "name": "height", "type": "'small' | 'initial' | 'large' | 'medium' | 'auto' | 'fit-content' | 'xsmall' | 'xlarge'", "required": false, "description": "", "defaultValue": "" }, { "name": "width", "type": "'small' | 'large' | 'medium' | 'auto' | 'xlarge' | 'xxlarge'", "required": false, "description": "", "defaultValue": "" }, { "name": "pinPosition", "type": "boolean", "required": false, "description": "If true, the overlay will attempt to prevent position shifting when sitting at the top of the anchor.", "defaultValue": "false" }, { "name": "variant", "type": "{ regular?: 'anchored', narrow?: 'anchored' | 'fullscreen' }", "required": false, "description": "Optional prop to set variant for narrow screen sizes", "defaultValue": "{ regular: 'anchored', narrow: 'anchored' }" }, { "name": "displayCloseButton", "type": "boolean", "required": false, "description": "If true, a close button will be displayed in the top right corner of the overlay when on fullscreen mode.", "defaultValue": "true" }, { "name": "closeButtonProps", "type": "Partial", "required": false, "description": "Props to be spread on the close button in fullscreen mode.", "defaultValue": "{}" } ] }, "autocomplete": { "source": "https://github.com/primer/react/tree/main/packages/react/src/Autocomplete", "id": "autocomplete", "name": "Autocomplete", "status": "alpha", "a11yReviewed": "2025-01-08", "stories": [ { "id": "components-autocomplete--default", "code": "() => {\n return (\n event.preventDefault()}\n >\n \n \n Label\n \n \n \n \n \n \n \n \n \n )\n}" }, { "id": "components-autocomplete-features--with-token-input", "code": "() => {\n const [tokens, setTokens] = useState([])\n const selectedTokenIds = tokens.map((token) => token.id)\n const [selectedItemIds, setSelectedItemIds] =\n useState>(selectedTokenIds)\n const onTokenRemove: (tokenId: string | number) => void = (tokenId) => {\n setTokens(tokens.filter((token) => token.id !== tokenId))\n setSelectedItemIds(selectedItemIds.filter((id) => id !== tokenId))\n }\n const onSelectedChange = (newlySelectedItems: Datum | Datum[]) => {\n if (!Array.isArray(newlySelectedItems)) {\n return\n }\n setSelectedItemIds(newlySelectedItems.map((item) => item.id))\n if (newlySelectedItems.length < selectedItemIds.length) {\n const newlySelectedItemIds = newlySelectedItems.map(({ id }) => id)\n const removedItemIds = selectedTokenIds.filter(\n (id) => !newlySelectedItemIds.includes(id),\n )\n for (const removedItemId of removedItemIds) {\n onTokenRemove(removedItemId)\n }\n return\n }\n setTokens(\n newlySelectedItems.map(({ id, text }) => ({\n id,\n text,\n })),\n )\n }\n return (\n
    \n \n \n Default label\n \n \n \n \n \n \n \n \n
    \n )\n}" }, { "id": "components-autocomplete-features--add-new-item", "code": "() => {\n const [inputValue, setInputValue] = React.useState('')\n return (\n
    \n \n \n Label\n \n \n {\n setInputValue(e.currentTarget.value)\n }}\n />\n \n item.text).includes(inputValue)\n ? {\n text: inputValue,\n id: inputValue,\n handleAddItem: (selectedItem) => {\n // eslint-disable-next-line no-console\n console.log('added item:', selectedItem)\n return\n },\n }\n : undefined\n }\n items={items}\n />\n \n \n \n
    \n )\n}" }, { "id": "components-autocomplete-features--custom-search-filter-fn", "code": "() => {\n const [filterVal, setFilterVal] = useState('')\n const handleChange: ChangeEventHandler = (e) => {\n setFilterVal(e.currentTarget.value)\n }\n const customFilterFn = (item: Datum) => item.text.includes(filterVal)\n return (\n
    \n \n \n Default label\n \n \n \n \n \n \n \n \n Items in dropdown are filtered if their text has no part that matches\n the input value\n \n \n
    \n )\n}" }, { "id": "components-autocomplete-features--custom-sort-after-menu-close", "code": "() => {\n const [selectedItemIds, setSelectedItemIds] = useState>([])\n const isItemSelected = (itemId: string) => selectedItemIds.includes(itemId)\n const onSelectedChange = (newlySelectedItems: Datum | Datum[]) => {\n if (!Array.isArray(newlySelectedItems)) {\n return\n }\n setSelectedItemIds(newlySelectedItems.map((item) => item.id))\n }\n const customSortFn = (itemIdA: string, itemIdB: string) =>\n isItemSelected(itemIdA) === isItemSelected(itemIdB)\n ? 0\n : isItemSelected(itemIdA)\n ? 1\n : -1\n return (\n
    \n \n \n Default label\n \n \n \n \n \n \n \n \n When the dropdown closes, selected items are sorted to the end\n \n \n
    \n )\n}" }, { "id": "components-autocomplete-features--with-callback-when-overlay-open-state-changes", "code": "() => {\n const [isMenuOpen, setIsMenuOpen] = useState(false)\n const onOpenChange = (isOpen: boolean) => {\n setIsMenuOpen(isOpen)\n }\n return (\n \n
    \n
    \n \n \n Default label\n \n \n \n \n \n \n \n \n
    \n\n
    \n The menu is {isMenuOpen ? 'open' : 'closed'}\n
    \n
    \n     \n )\n}" }, { "id": "components-autocomplete-features--async-loading-of-items", "code": "(args: FormControlArgs) => {\n const { parentArgs, labelArgs, captionArgs, validationArgs } =\n getFormControlArgsByChildComponent(args)\n const { menuArgs, overlayArgs, textInputArgs } = getArgsByChildComponent(args)\n const [loadedItems, setLoadedItems] = useState([])\n const onOpenChange = (isOpen: boolean) => {\n if (isOpen) {\n setTimeout(() => {\n setLoadedItems(items)\n }, 1500)\n }\n }\n return (\n
    \n \n \n \n \n \n \n \n \n {captionArgs.children && }\n {validationArgs.children && validationArgs.variant && (\n \n )}\n \n
    \n )\n}" }, { "id": "components-autocomplete-features--rendering-the-menu-outside-an-overlay", "code": "() => {\n return (\n
    \n \n \n Default label\n \n \n \n \n \n \n
    \n )\n}" }, { "id": "components-autocomplete-features--custom-overlay-menu-anchor", "code": "() => {\n const menuAnchorRef = useRef(null)\n return (\n
    \n \n \n Default label\n \n }\n className={classes.AnchorContainer}\n >\n \n \n \n \n \n \n \n \n The overlay menu position is anchored to the div with the black border\n instead of to the text input\n \n \n
    \n )\n}" }, { "id": "components-autocomplete-features--in-overlay-with-custom-scroll-container-ref", "code": "() => {\n const scrollContainerRef = useRef(null)\n const inputRef = useRef(null)\n const triggerRef = useRef(null)\n const [isOpen, setIsOpen] = useState(false)\n const [selectedItem, setSelectedItem] = useState()\n const handleOpen = () => {\n setIsOpen(true)\n inputRef.current && inputRef.current.focus()\n }\n const selectChange = (item: Datum[] | Datum) => {\n setIsOpen(false)\n if (Array.isArray(item) && item.length) setSelectedItem(item[0])\n triggerRef.current?.focus()\n }\n return (\n
    \n \n Selected item: {selectedItem ? selectedItem.text : 'none'}\n \n\n setIsOpen(false)}\n width=\"large\"\n focusTrapSettings={{\n initialFocusRef: inputRef,\n }}\n side=\"inside-top\"\n anchorRef={triggerRef}\n renderAnchor={(props) => (\n \n )}\n preventOverflow={false}\n >\n \n
    \n
    \n \n
    \n }\n className={classes.OverlayScroll}\n >\n \n
    \n \n     \n \n \n )\n}" }, { "id": "components-autocomplete-features--in-a-dialog", "code": "() => {\n const outerContainerRef = useRef(null)\n const [mounted, setMounted] = useState(false)\n const [isDialogOpen, setIsDialogOpen] = useState(false)\n useEffect(() => {\n if (outerContainerRef.current instanceof HTMLElement) {\n registerPortalRoot(outerContainerRef.current, 'outerContainer')\n setMounted(true)\n }\n }, [isDialogOpen])\n return (\n <>\n \n setIsDialogOpen(false)}\n >\n
    \n
    \n {mounted ? (\n \n \n Default label\n \n \n \n \n \n \n \n \n ) : null}\n
    \n
    \n \n

    \n The Autocomplete.Overlay is portalled to a div inside the Dialog to\n ensure it appears above the dialog in the stacking context.\n

    \n \n )\n}" } ], "importPath": "@primer/react", "props": [ { "name": "children", "type": "React.ReactNode" }, { "name": "id", "type": "string", "description": "May be used to customize how the ID is set on the text input to be used by ARIA attributes on related elements.", "defaultValue": "" } ], "subcomponents": [ { "name": "Autocomplete.Input", "props": [ { "name": "as", "type": "React.ElementType", "defaultValue": "TextInput" }, { "name": "openOnFocus", "type": "boolean", "defaultValue": "false", "description": "Whether the associated autocomplete menu should open on an input focus event", "deprecated": true } ], "passthrough": { "element": "TextInput", "url": "/react/TextInput" } }, { "name": "Autocomplete.Overlay", "props": [ { "name": "menuAnchorRef", "type": "React.RefObject" }, { "name": "children", "type": "React.ReactNode" }, { "name": "overlayProps", "deprecated": true, "type": "Partial", "description": "Props to be spread on the internal `Overlay` component." } ], "passthrough": { "element": "Overlay", "url": "/react/Overlay" } }, { "name": "Autocomplete.Menu", "props": [ { "name": "items", "required": true, "type": "T[]", "description": "The options for field values that are displayed in the dropdown menu. One or more may be selected depending on the value of the `selectionVariant` prop." }, { "name": "selectedItemIds", "required": true, "type": "string[]", "description": "The IDs of the selected items" }, { "name": "aria-labelledby", "required": true, "type": "string" }, { "name": "addNewItem", "type": "Omit & { handleAddItem: (item: Omit) => void; }", "description": "A menu item that is used to allow users make a selection that is not available in the array passed to the `items` prop. This menu item gets appended to the end of the list of options." }, { "name": "emptyStateText", "type": "React.ReactNode | false", "description": "The text that appears in the menu when there are no options in the array passed to the `items` prop." }, { "name": "filterFn", "type": "(item: T, i: number) => boolean", "description": "A custom function used to filter the options in the array passed to the `items` prop. By default, we filter out items that don't match the value of the autocomplete text input. The default filter is not case-sensitive." }, { "name": "loading", "type": "boolean", "description": "Whether the data is loading for the menu items" }, { "name": "sortOnCloseFn", "type": "(itemIdA: string | number, itemIdB: string | number) => number", "description": "The sort function that is applied to the options in the array passed to the `items` prop after the user closes the menu. By default, selected items are sorted to the top after the user closes the menu." }, { "name": "selectionVariant", "type": "'single' | 'multiple'", "description": "Whether there can be one item selected from the menu or multiple items selected from the menu" }, { "name": "onOpenChange", "type": "(open: boolean) => void", "description": "Function that gets called when the menu is opened or closed" }, { "name": "onSelectedChange", "type": "(item: T | T[]) => void", "description": "The function that is called when an item in the list is selected or deselected" }, { "name": "customScrollContainerRef", "type": "React.MutableRefObject", "description": "If the menu is rendered in a scrolling element other than the `Autocomplete.Overlay` component, pass the ref of that element to `customScrollContainerRef` to ensure the container automatically scrolls when the user highlights an item in the menu that is outside the scroll container" } ] } ] }, "avatar": { "source": "https://github.com/primer/react/tree/main/packages/react/src/Avatar", "id": "avatar", "name": "Avatar", "status": "alpha", "a11yReviewed": "2025-01-08", "stories": [ { "id": "components-avatar--default", "code": "() => " }, { "id": "components-avatar-features--square", "code": "() => (\n \n)" }, { "id": "components-avatar-features--size", "code": "() => (\n
    \n \n \n \n \n \n \n \n \n \n \n \n \n
    \n)" }, { "id": "components-avatar-features--size-responsive", "code": "() => (\n
    \n \n \n \n \n \n \n \n \n \n \n
    \n)" } ], "importPath": "@primer/react", "props": [ { "name": "alt", "type": "string", "defaultValue": "''", "description": "Provide alt text when the avatar is used without a name next to it." }, { "name": "size", "type": "number | { narrow?: number; regular?: number; wide?: number; }", "defaultValue": "20", "description": "The size of the avatar in pixels." }, { "name": "square", "type": "boolean", "defaultValue": "false", "description": "If true, the avatar will be square instead of circular." }, { "name": "src", "type": "string", "required": false, "description": "URL of the avatar image.", "defaultValue": "" } ], "subcomponents": [] }, "avatar_stack": { "source": "https://github.com/primer/react/tree/main/packages/react/src/AvatarStack", "id": "avatar_stack", "name": "AvatarStack", "status": "alpha", "a11yReviewed": "2025-01-08", "stories": [ { "id": "components-avatarstack-features--align-left", "code": "() => (\n \n \n \n \n \n \n)" }, { "id": "components-avatarstack-features--align-right", "code": "() => (\n \n \n \n \n \n \n)" }, { "id": "components-avatarstack-features--disable-expand-on-hover", "code": "() => (\n \n \n \n \n \n \n)" }, { "id": "components-avatarstack-features--custom-size-on-parent", "code": "() => (\n \n \n \n \n \n \n)" }, { "id": "components-avatarstack-features--custom-size-on-parent-responsive", "code": "() => (\n \n \n \n \n \n \n)" }, { "id": "components-avatarstack-features--custom-size-on-children", "code": "() => (\n \n \n \n \n \n \n)" }, { "id": "components-avatarstack-features--custom-size-on-children-responsive", "code": "() => (\n \n \n \n \n \n \n)" }, { "id": "components-avatarstack-features--with-single-avatar", "code": "() => (\n \n \n \n)" } ], "importPath": "@primer/react", "props": [ { "name": "children", "type": "ReactNode", "description": "A set of Avatar components to stack", "defaultValue": "" }, { "name": "alignRight", "type": "boolean", "defaultValue": "false", "description": "Align the avatars to the right" }, { "name": "disableExpand", "type": "boolean", "defaultValue": "false", "description": "Do not spread the avatars on hover" }, { "name": "variant", "type": "'cascade' | 'stack'", "defaultValue": "'cascade'", "description": "The style of overlapping avatars. 'cascade' increases the overlap for 3rd+ avatars, while 'stack' uses a uniform overlap." }, { "name": "shape", "type": "'circle' | 'square'", "defaultValue": "'circle'", "description": "The shape of the avatars." }, { "name": "size", "type": "number | { narrow?: number; regular?: number; wide?: number; }", "defaultValue": "20", "description": "The size of the avatar children in pixels." }, { "name": "className", "type": "string", "description": "Class name for custom styling.", "defaultValue": "" } ], "subcomponents": [] }, "banner": { "source": "https://github.com/primer/react/tree/main/packages/react/src/Banner", "id": "banner", "name": "Banner", "status": "alpha", "a11yReviewed": "2025-01-08", "importPath": "@primer/react", "stories": [ { "id": "components-banner--default", "code": "() => {\n return (\n \n GitHub users are{' '}\n \n now required\n {' '}\n to enable two-factor authentication as an additional security measure.\n \n }\n primaryAction={Button}\n secondaryAction={Button}\n />\n )\n}" }, { "id": "components-banner-features--critical", "code": "() => {\n return (\n \n GitHub users are{' '}\n \n now required\n {' '}\n to enable two-factor authentication as an additional security measure.\n \n }\n variant=\"critical\"\n />\n )\n}" }, { "id": "components-banner-features--info", "code": "() => {\n return (\n \n GitHub users are{' '}\n \n now required\n {' '}\n to enable two-factor authentication as an additional security measure.\n \n }\n onDismiss={action('onDismiss')}\n variant=\"info\"\n >\n )\n}" }, { "id": "components-banner-features--success", "code": "() => {\n return (\n \n GitHub users are{' '}\n \n now required\n {' '}\n to enable two-factor authentication as an additional security measure.\n \n }\n onDismiss={action('onDismiss')}\n variant=\"success\"\n />\n )\n}" }, { "id": "components-banner-features--upsell", "code": "() => {\n return (\n \n GitHub users are{' '}\n \n now required\n {' '}\n to enable two-factor authentication as an additional security measure.\n \n }\n onDismiss={action('onDismiss')}\n variant=\"upsell\"\n />\n )\n}" }, { "id": "components-banner-features--warning", "code": "() => {\n return (\n \n GitHub users are{' '}\n \n now required\n {' '}\n to enable two-factor authentication as an additional security measure.\n \n }\n onDismiss={action('onDismiss')}\n variant=\"warning\"\n />\n )\n}" }, { "id": "components-banner-features--dismiss", "code": "() => {\n return (\n \n GitHub users are{' '}\n \n now required\n {' '}\n to enable two-factor authentication as an additional security measure.\n \n }\n onDismiss={action('onDismiss')}\n />\n )\n}" }, { "id": "components-banner-features--dismiss-with-actions", "code": "() => {\n return (\n \n GitHub users are{' '}\n \n now required\n {' '}\n to enable two-factor authentication as an additional security measure.\n \n }\n onDismiss={action('onDismiss')}\n primaryAction={Button}\n secondaryAction={Button}\n />\n )\n}" }, { "id": "components-banner-features--with-hidden-title", "code": "() => {\n return (\n \n GitHub users are{' '}\n \n now required\n {' '}\n to enable two-factor authentication as an additional security measure.\n \n }\n variant=\"warning\"\n />\n )\n}" }, { "id": "components-banner-features--with-hidden-title-and-actions", "code": "() => {\n return (\n \n GitHub users are{' '}\n \n now required\n {' '}\n to enable two-factor authentication as an additional security measure.\n \n }\n variant=\"warning\"\n primaryAction={Button}\n secondaryAction={Button}\n />\n )\n}" }, { "id": "components-banner-features--dismissible-with-hidden-title-and-actions", "code": "() => {\n return (\n \n GitHub users are{' '}\n \n now required\n {' '}\n to enable two-factor authentication as an additional security measure.\n \n }\n onDismiss={action('onDismiss')}\n variant=\"warning\"\n primaryAction={Button}\n secondaryAction={Button}\n />\n )\n}" }, { "id": "components-banner-features--dismissible-with-hidden-title-and-secondary-action", "code": "() => {\n return (\n \n GitHub users are{' '}\n \n now required\n {' '}\n to enable two-factor authentication as an additional security measure.\n \n }\n onDismiss={action('onDismiss')}\n variant=\"warning\"\n secondaryAction={\n \n Button\n \n }\n />\n )\n}" }, { "id": "components-banner-features--with-actions", "code": "() => {\n return (\n \n GitHub users are{' '}\n \n now required\n {' '}\n to enable two-factor authentication as an additional security measure.\n \n }\n primaryAction={Button}\n secondaryAction={Button}\n variant=\"warning\"\n />\n )\n}" }, { "id": "components-banner-features--custom-icon", "code": "() => {\n return (\n }\n onDismiss={action('onDismiss')}\n variant=\"upsell\"\n />\n )\n}" }, { "id": "components-banner-examples--with-announcement", "code": "() => {\n type Choice = 'one' | 'two' | 'three'\n const messages: Map = new Map([\n ['one', 'This is a message for choice one'],\n ['two', 'This is a message for choice two'],\n ['three', 'This is a message for choice three'],\n ])\n const [selected, setSelected] = React.useState('one')\n return (\n <>\n {messages.get(selected)}}\n onDismiss={action('onDismiss')}\n primaryAction={Button}\n secondaryAction={\n Button\n }\n />\n {\n setSelected(selected as Choice)\n }}\n className={classes.RadioGroupWithTopMargin}\n >\n Choices\n \n \n Choice one\n \n \n \n Choice two\n \n \n \n Choice three\n \n \n \n )\n}" } ], "props": [ { "name": "aria-label", "type": "string", "description": "Provide an optional label to override the default name for the Banner landmark region" }, { "name": "className", "type": "string", "description": "Provide an optional className to add to the outermost element rendered by the Banner" }, { "name": "description", "type": "React.ReactNode", "description": "Provide an optional description for the Banner. This should provide supplemental information about the Banner" }, { "name": "hideTitle", "type": "boolean", "description": "Whether to hide the title visually." }, { "name": "icon", "type": "React.ReactNode", "description": "Provide a custom icon for the Banner. This is only available when `variant` is `info` or `upsell`", "deprecated": true }, { "name": "leadingVisual", "type": "React.ReactNode", "description": "Provide a custom leading visual for the Banner. This is only available when `variant` is `info` or `upsell`" }, { "name": "onDismiss", "type": "() => void", "description": "Optionally provide a handler to be called when the banner is dismissed. Providing this prop will show a dismiss button" }, { "name": "primaryAction", "type": "React.ReactNode", "description": "" }, { "name": "secondaryAction", "type": "React.ReactNode", "description": "" }, { "name": "title", "type": "React.ReactNode", "description": "The title for the Banner. This will be used as the accessible name and is required unless `Banner.Title` is used as a child" }, { "name": "variant", "type": "'critical' | 'info' | 'success' | 'upsell' | 'warning'", "description": "Specify the type of the Banner" }, { "name": "layout", "type": "'default' | 'compact'", "description": "Specify the layout of the Banner. Compact layout will reduce the padding." }, { "name": "actionsLayout", "type": "'default' | 'inline' | 'stacked'", "description": "Override the responsive layout of the action buttons. 'inline' layout will display the buttons inline with the title and description, while 'stacked' layout will always render the buttons in a new row." }, { "name": "flush", "type": "boolean", "defaultValue": "false", "description": "Full width banner specifically for use within confined spaces, such as dialogs, tables, cards, or boxes where available space is limited." } ], "subcomponents": [ { "name": "Banner.Title", "props": [ { "name": "as", "type": "'h2' | 'h3' | 'h4' | 'h5' | 'h6'" } ] }, { "name": "Banner.Description", "props": [ { "name": "className", "type": "string", "description": "Class name(s) for custom styling.", "defaultValue": "" } ] }, { "name": "Banner.PrimaryAction", "props": [], "passthrough": { "element": "Button", "url": "/react/Button" } }, { "name": "Banner.SecondaryAction", "props": [], "passthrough": { "element": "Button", "url": "/react/Button" } } ] }, "blankslate": { "source": "https://github.com/primer/react/tree/main/packages/react/src/Blankslate", "id": "blankslate", "name": "Blankslate", "status": "draft", "a11yReviewed": "2025-01-08", "stories": [ { "id": "experimental-components-blankslate--default", "code": "() => (\n \n \n \n \n Welcome to the mona wiki!\n \n Wikis provide a place in your repository to lay out the roadmap of your\n project, show the current status, and document software better, together.\n \n \n Create the first page\n \n \n Learn more about wikis\n \n \n)" }, { "id": "experimental-components-blankslate-features--with-visual", "code": "() => (\n \n \n \n \n Blankslate heading\n \n Use it to provide information when no dynamic content exists.\n \n \n)" }, { "id": "experimental-components-blankslate-features--with-primary-action-as-link", "code": "() => (\n \n \n \n \n Blankslate heading\n \n Use it to provide information when no dynamic content exists.\n \n Primary action\n \n)" }, { "id": "experimental-components-blankslate-features--with-primary-action-as-button", "code": "() => {\n const [isOpen, setIsOpen] = React.useState(false)\n const onDialogClose = React.useCallback(() => setIsOpen(false), [])\n return (\n <>\n \n \n \n \n Blankslate heading\n \n Use it to provide information when no dynamic content exists.\n \n setIsOpen(true)}>\n Primary action\n \n \n {isOpen ? (\n \n Deleting the universe could have disastrous effects, including but not\n limited to destroying all life on Earth.\n \n ) : null}\n \n )\n}" }, { "id": "experimental-components-blankslate-features--with-secondary-action", "code": "() => (\n \n \n \n \n Blankslate heading\n \n Use it to provide information when no dynamic content exists.\n \n \n Secondary action\n \n \n)" }, { "id": "experimental-components-blankslate-features--with-border", "code": "() => (\n \n \n \n \n Blankslate heading\n \n Use it to provide information when no dynamic content exists.\n \n \n)" }, { "id": "experimental-components-blankslate-features--narrow", "code": "() => (\n \n \n \n \n Blankslate heading\n \n Use it to provide information when no dynamic content exists.\n \n \n)" }, { "id": "experimental-components-blankslate-features--spacious", "code": "() => (\n \n \n \n \n Blankslate heading\n \n Use it to provide information when no dynamic content exists.\n \n \n)" } ], "importPath": "@primer/react/experimental", "props": [ { "name": "border", "type": "boolean", "description": "Add a border around this component" }, { "name": "narrow", "type": "boolean", "description": "" }, { "name": "spacious", "type": "boolean", "description": "" }, { "name": "className", "type": "string", "description": "Class name(s) for custom styling.", "defaultValue": "" }, { "name": "size", "type": "'small' | 'medium' | 'large'", "description": "The size of the componeont", "defaultValue": "'medium'" } ], "subcomponents": [ { "name": "Blankslate.Visual", "props": [] }, { "name": "Blankslate.Heading", "props": [ { "name": "as", "type": "'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'" } ] }, { "name": "Blankslate.Description", "props": [] }, { "name": "Blankslate.PrimaryAction", "props": [ { "name": "href", "type": "string", "required": false, "description": "Link to complete primary action. If defined, will render as an anchor instead of a button." } ] }, { "name": "Blankslate.SecondaryAction", "props": [ { "name": "href", "type": "string", "description": "Link to complete secondary action" } ] } ] }, "branch_name": { "source": "https://github.com/primer/react/tree/main/packages/react/src/BranchName", "id": "branch_name", "name": "BranchName", "status": "alpha", "a11yReviewed": "2025-01-08", "stories": [ { "id": "components-branchname--default", "code": "() => branch_name" }, { "id": "components-branchname-features--with-branch-icon", "code": "() => (\n \n \n \n branch_name\n \n \n)" }, { "id": "components-branchname-features--not-a-link", "code": "() => branch_name_as_span" } ], "importPath": "@primer/react", "props": [ { "name": "ref", "type": "React.RefObject" }, { "name": "as", "type": "React.ElementType", "defaultValue": "\"a\"" } ], "subcomponents": [] }, "breadcrumbs": { "source": "https://github.com/primer/react/tree/main/packages/react/src/Breadcrumbs", "id": "breadcrumbs", "name": "Breadcrumbs", "status": "alpha", "a11yReviewed": "2025-01-08", "stories": [ { "id": "components-breadcrumbs--default", "code": "() => (\n \n Home\n About\n \n Team\n \n \n)" } ], "importPath": "@primer/react", "props": [ { "name": "className", "type": "string", "required": false, "description": "Additional CSS class names to apply to the breadcrumbs container", "defaultValue": "" }, { "name": "children", "type": "Breadcrumbs.Item[]", "defaultValue": "", "description": "Breadcrumb items to render. Each item should be a Breadcrumbs.Item component." }, { "name": "overflow", "type": "'wrap' | 'menu' | 'menu-with-root'", "required": false, "description": "How to handle overflow when breadcrumbs don't fit in the container. 'wrap' allows items to wrap to new lines. 'menu' collapses items into an overflow menu. 'menu-with-root' also collapses items into an overflow menu but includes the root (first) breadcrumb in the menu so only the last items remain visible.", "defaultValue": "'wrap'" } ], "subcomponents": [ { "name": "Breadcrumbs.Item", "props": [ { "name": "selected", "type": "boolean", "defaultValue": "false", "description": "Whether this item represents the current page. Sets aria-current='page' for accessibility." }, { "name": "to", "type": "string | Partial", "required": false, "description": "Used when the item is rendered using a component like React Router's `Link`. The path to navigate to.", "defaultValue": "" }, { "name": "href", "type": "string", "required": false, "description": "The URL that the breadcrumb item links to. Used with regular anchor elements." }, { "name": "children", "type": "React.ReactNode", "required": true, "description": "The content to display inside the breadcrumb item, typically text." }, { "name": "ref", "type": "React.RefObject" }, { "name": "as", "type": "React.ElementType", "defaultValue": "\"a\"" } ], "passthrough": { "element": "a", "url": "https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#Attributes" } } ] }, "button": { "source": "https://github.com/primer/react/tree/main/packages/react/src/Button", "id": "button", "name": "Button", "status": "alpha", "a11yReviewed": "2025-01-08", "stories": [ { "id": "components-button--default", "code": "() => " }, { "id": "components-button-features--primary", "code": "() => " }, { "id": "components-button-features--danger", "code": "() => " }, { "id": "components-button-features--invisible", "code": "() => " }, { "id": "components-button-features--link", "code": "() => " }, { "id": "components-button-features--leading-visual", "code": "() => " }, { "id": "components-button-features--trailing-visual", "code": "() => " }, { "id": "components-button-features--trailing-counter", "code": "() => {\n const [count, setCount] = useState(0)\n const onClick = () => {\n setCount(count + 1)\n announce(`Watch ${count + 1}`)\n }\n return (\n <>\n \n \n

    \n In this example, a live region has been implemented to communicate the\n change.\n

    \n \n )\n}" }, { "id": "components-button-features--trailing-counter-with-no-text", "code": "() => \n \n \n \n \n \n \n \n \n \n

    \n In these examples, a live region has been implemented to communicate the\n change.\n

    \n \n )\n}" }, { "id": "components-button-features--trailing-action", "code": "() => " }, { "id": "components-button-features--block", "code": "() => " }, { "id": "components-button-features--disabled", "code": "() => (\n \n \n \n \n \n \n)" }, { "id": "components-button-features--inactive", "code": "() => (\n \n Inactive\n \n \n \n \n \n)" }, { "id": "components-button-features--small", "code": "() => " }, { "id": "components-button-features--medium", "code": "() => " }, { "id": "components-button-features--large", "code": "() => " }, { "id": "components-button-features--loading", "code": "() => " }, { "id": "components-button-features--loading-custom-announcement", "code": "() => (\n \n)" }, { "id": "components-button-features--loading-with-leading-visual", "code": "() => (\n \n)" }, { "id": "components-button-features--loading-with-trailing-visual", "code": "() => (\n \n)" }, { "id": "components-button-features--loading-with-trailing-action", "code": "() => (\n \n)" }, { "id": "components-button-features--loading-trigger", "code": "() => {\n const [isLoading, setIsLoading] = useState(false)\n const handleClick = () => {\n setIsLoading(true)\n }\n return (\n \n Export\n \n )\n}" }, { "id": "components-button-features--label-wrap", "code": "() => {\n return (\n \n \n \n \n \n \n )\n}" }, { "id": "components-button-features--inactive-button-with-tooltip", "code": "() => (\n \n \n \n)" }, { "id": "components-button-features--expanded-button", "code": "() => (\n \n \n \n \n \n \n)" } ], "importPath": "@primer/react", "props": [ { "name": "alignContent", "type": "'start' | 'center'", "description": "Content alignment for when visuals are present." }, { "name": "as", "type": "React.ElementType", "defaultValue": "'button'" }, { "name": "href", "type": "string", "description": "**May only be used when `as` is set to 'a'**.\n The URL the button links to. If `as` is set to 'a', this prop is required." }, { "name": "block", "type": "boolean", "description": "Allow button width to fill its container." }, { "name": "children", "required": true, "type": "React.ReactNode", "description": "The content of the button." }, { "name": "count", "type": "number", "description": "For counter buttons, the number to display." }, { "name": "inactive", "type": "boolean", "description": "Whether the button looks visually disabled, but can still accept all the same interactions as an enabled button.\nThis is intended to be used when a system error such as an outage prevents the button from performing its usual action.\nInactive styles are slightly different from disabled styles because inactive buttons need to have an accessible color contrast ratio. This is because inactive buttons can have tooltips or perform an action such as opening a dialog explaining why it's inactive.\nIf both `disabled` and `inactive` are true, `disabled` takes precedence." }, { "name": "leadingIcon", "type": "React.ComponentType", "description": "An icon to display before the button text.", "deprecated": true }, { "name": "leadingVisual", "type": "React.ElementType", "description": "A visual to display before the button text." }, { "name": "loading", "type": "boolean", "description": "When true, the button is in a loading state." }, { "name": "loadingAnnouncement", "type": "string", "description": "The content to announce to screen readers when loading. This requires `loading` prop to be true" }, { "name": "ref", "type": "React.RefObject" }, { "name": "size", "type": "'small'\n| 'medium'\n| 'large'", "defaultValue": "'medium'" }, { "name": "trailingIcon", "type": "React.ComponentType", "description": "An icon to display after the button text.", "deprecated": true }, { "name": "trailingVisual", "type": "React.ElementType", "description": "A visual to display after the button text." }, { "name": "trailingAction", "type": "React.ElementType", "description": "Trailing action appears to the right of the trailing visual and is always locked to the end" }, { "name": "variant", "type": "'default'\n| 'primary'\n| 'danger'\n| 'invisible'\n| 'link'", "defaultValue": "'default'", "description": "Change the visual style of the button." }, { "name": "labelWrap", "type": "boolean", "defaultValue": "false", "description": "Whether the button label should wrap to multiple lines of it is longer than the button width." }, { "name": "disabled", "type": "boolean", "description": "Avoid disabling buttons because it will make them inaccessible to users who rely on keyboard navigation. Buttons that are disabled can not be clicked, selected, or navigated through.", "defaultValue": "" } ], "passthrough": { "element": "button", "url": "https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes" } }, "icon_button": { "source": "https://github.com/primer/react/tree/main/packages/react/src/Button", "id": "icon_button", "name": "IconButton", "status": "alpha", "a11yReviewed": "2025-01-08", "stories": [ { "id": "components-iconbutton--default", "code": "() => " }, { "id": "components-iconbutton-features--primary", "code": "() => " }, { "id": "components-iconbutton-features--danger", "code": "() => " }, { "id": "components-iconbutton-features--invisible", "code": "() => " }, { "id": "components-iconbutton-features--disabled", "code": "() => " }, { "id": "components-iconbutton-features--small", "code": "() => " }, { "id": "components-iconbutton-features--medium", "code": "() => " }, { "id": "components-iconbutton-features--large", "code": "() => " }, { "id": "components-iconbutton-features--with-description", "code": "() => (\n \n)" }, { "id": "components-iconbutton-features--external-tooltip", "code": "() => (\n \n \n \n)" }, { "id": "components-iconbutton-features--as-a-menu-anchor", "code": "() => (\n \n \n \n \n\n \n \n alert('Copy link clicked')}>\n Copy link\n ⌘C\n \n alert('Quote reply clicked')}>\n Quote reply\n ⌘Q\n \n alert('Edit comment clicked')}>\n Edit comment\n ⌘E\n \n \n alert('Delete file clicked')}\n >\n Delete file\n ⌘D\n \n \n \n \n)" }, { "id": "components-iconbutton-features--loading", "code": "() => (\n \n)" }, { "id": "components-iconbutton-features--loading-trigger", "code": "() => {\n const [isLoading, setIsLoading] = useState(false)\n const handleClick = () => {\n setIsLoading(true)\n setTimeout(() => {\n setIsLoading(false)\n }, 3000)\n }\n return (\n \n )\n}" }, { "id": "components-iconbutton-features--keybinding-hint-on-description", "code": "() => (\n \n)" }, { "id": "components-iconbutton-features--keybinding-hint", "code": "() => " } ], "importPath": "@primer/react", "props": [ { "name": "children", "type": "React.ReactNode", "defaultValue": "", "required": true, "description": "This will be the Button description." }, { "name": "as", "type": "React.ElementType", "defaultValue": "'button'" }, { "name": "href", "type": "string", "description": "**May only be used when `as` is set to 'a'**.\n The URL the button links to. If `as` is set to 'a', this prop is required." }, { "name": "variant", "type": "'default' | 'primary' | 'danger' | 'invisible' | 'link'", "defaultValue": "", "description": "Changes the look and feel of the button which is different for each variant" }, { "name": "size", "type": "'small' | 'medium' | 'large'", "defaultValue": "", "description": "Changes the size of the icon button component" }, { "name": "inactive", "type": "boolean", "description": "Whether the button looks visually disabled, but can still accept all the same interactions as an enabled button." }, { "name": "icon", "type": "Component", "defaultValue": "", "description": "provide an octicon. It will be placed in the center of the button" }, { "name": "aria-label", "type": "string", "defaultValue": "", "description": "Use an aria label to describe the functionality of the button. Please refer to [our guidance on alt text](https://primer.style/guides/accessibility/alternative-text-for-images) for tips on writing good alternative text." }, { "name": "keyshortcuts", "type": "string", "defaultValue": "", "deprecated": true, "description": "Use `keybindingHint` instead." }, { "name": "keybindingHint", "type": "string | string[]", "description": "Optional keybinding hint to show in the tooltip for this button. Pass a string for a single shortcut or an array of strings to show multiple shortcuts joined with \"or\". See the `KeybindingHint` component documentation for the correct format. Has no effect if tooltip is overridden or disabled. Does **not** bind any keybindings for this button - this is only for visual hints." }, { "name": "tooltipDirection", "type": "'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w' | 'nw'", "defaultValue": "'s'", "description": "The direction of the tooltip.", "required": false }, { "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": "" } ], "subcomponents": [] }, "button_group": { "source": "https://github.com/primer/react/tree/main/packages/react/src/ButtonGroup", "id": "button_group", "name": "ButtonGroup", "status": "alpha", "a11yReviewed": "2025-01-08", "stories": [ { "id": "components-buttongroup--default", "code": "() => (\n \n \n \n \n \n)" }, { "id": "components-buttongroup-features--icon-buttons", "code": "() => (\n \n {/* We can remove these unsafe props after we resolve https://github.com/primer/react/issues/4129 */}\n \n \n \n)" }, { "id": "components-buttongroup-features--loading-buttons", "code": "() => {\n const handleClick = () => {}\n return (\n \n \n \n \n \n \n \n )\n}" }, { "id": "components-buttongroup-features--dropdown-split", "code": "() => {\n const actions = ['Action one', 'Action two', 'Action three']\n const [selectedActionIndex, setSelectedActionIndex] =\n React.useState(0)\n const selectedAction = actions[selectedActionIndex]\n return (\n \n {\n alert(`Activated ${selectedAction}`)\n }}\n >\n {selectedAction}\n \n \n \n \n \n {actions.map((action, index) => {\n return (\n {\n setSelectedActionIndex(index)\n }}\n >\n {action}\n \n )\n })}\n \n \n \n \n )\n}" }, { "id": "components-buttongroup-features--as-toolbar", "code": "() => (\n \n \n \n \n \n)" } ], "importPath": "@primer/react", "props": [ { "name": "ref", "type": "React.RefObject" } ], "subcomponents": [] }, "card": { "source": "https://github.com/primer/react/tree/main/packages/react/src/Card", "id": "card", "name": "Card", "status": "draft", "a11yReviewed": false, "importPath": "@primer/react/experimental", "stories": [ { "id": "experimental-components-card--default", "code": "() => {\n return (\n \n \n Card Heading\n \n This is a description of the card providing supplemental information.\n \n \n 3 contributors\n \n \n )\n}" }, { "id": "experimental-components-card-features--with-image", "code": "() => {\n return (\n \n \n Card with Image\n \n This card uses an edge-to-edge image instead of an icon.\n \n \n )\n}" }, { "id": "experimental-components-card-features--with-metadata", "code": "() => {\n return (\n \n \n primer/react\n \n {\n \"GitHub's design system implemented as React components for building consistent user interfaces.\"\n }\n \n \n \n 1.2k stars\n \n \n )\n}" }, { "id": "experimental-components-card-features--with-menu", "code": "() => {\n return (\n \n \n primer/react\n \n {\n \"GitHub's design system implemented as React components for building consistent user interfaces.\"\n }\n \n \n \n \n \n \n \n \n Star\n Watch\n Fork\n \n \n \n \n \n )\n}" }, { "id": "experimental-components-card-features--standalone-section", "code": "() => (\n \n \n primer/react\n \n {\n 'Standalone cards render as a labelled
    landmark. aria-labelledby is automatically wired to Card.Heading.'\n }\n \n \n)" }, { "id": "experimental-components-card-features--in-list", "code": "() => (\n
      \n
    • \n \n \n primer/react\n \n \n 1.2k stars\n \n \n
      • \n
    • \n \n \n primer/css\n \n \n 850 stars\n \n \n
      • \n
    • \n \n \n primer/octicons\n \n \n 2.1k stars\n \n \n
      • \n
    \n)" }, { "id": "experimental-components-card-features--interactive-content", "code": "() => {\n const repos = [\n {\n name: 'primer/react',\n },\n {\n name: 'primer/css',\n },\n {\n name: 'primer/octicons',\n },\n ]\n return (\n
      \n {repos.map((repo) => (\n
    • \n \n \n {repo.name}\n \n \n \n \n \n
      • \n ))}\n
    \n )\n}" } ], "props": [ { "name": "children", "type": "React.ReactNode", "required": true, "description": "The contents of the card. Provide either `Card.*` subcomponents (for example `Card.Heading`, `Card.Description`, `Card.Metadata`) or any custom content. A card with no children will not render." }, { "name": "className", "type": "string", "description": "CSS class name(s) for custom styling." }, { "name": "padding", "type": "'none' | 'condensed' | 'normal'", "defaultValue": "'normal'", "description": "Controls the internal padding of the Card." }, { "name": "borderRadius", "type": "'medium' | 'large'", "defaultValue": "'large'", "description": "Controls the border radius of the Card." }, { "name": "as", "type": "'div' | 'section'", "defaultValue": "'div'", "description": "The HTML element to render. Use `'section'` for **standalone** Cards (not inside a list of cards) so screen readers announce the Card as a labelled region. When `Card.Heading` is present, `aria-labelledby` is automatically wired. Use the default `'div'` when the Card is inside an `
  • ` of a list of cards." } ], "subcomponents": [ { "name": "Card.Icon", "props": [ { "name": "icon", "type": "React.ElementType", "description": "An Octicon or custom SVG icon to render." }, { "name": "aria-label", "type": "string", "description": "Accessible label for the icon. When omitted, the icon is treated as decorative." } ] }, { "name": "Card.Image", "props": [ { "name": "src", "type": "string", "description": "The image source URL." }, { "name": "alt", "type": "string", "defaultValue": "\"\"", "description": "Alt text for accessibility. Defaults to empty string (decorative)." } ] }, { "name": "Card.Heading", "props": [ { "name": "as", "type": "'h2' | 'h3' | 'h4' | 'h5' | 'h6'", "defaultValue": "'h3'", "description": "The heading level to render. When the parent Card uses `as=\"section\"`, the heading's `id` is automatically wired to the section's `aria-labelledby`." } ] }, { "name": "Card.Description", "props": [ { "name": "children", "type": "React.ReactNode", "required": true, "description": "The descriptive text for the card. Rendered inside a `

    ` element so should be flowing text content." } ] }, { "name": "Card.Action", "props": [ { "name": "children", "type": "React.ReactNode", "required": true, "description": "Interactive control for the top-right corner of the card." } ] }, { "name": "Card.Metadata", "props": [ { "name": "children", "type": "React.ReactNode", "required": true, "description": "Metadata content for the bottom of the card. Accepts any content: plain text, icons, or other Primer components." } ] } ] }, "checkbox": { "source": "https://github.com/primer/react/tree/main/packages/react/src/Checkbox", "id": "checkbox", "name": "Checkbox", "status": "alpha", "a11yReviewed": "2025-01-08", "stories": [ { "id": "components-checkbox--default", "code": "() => (\n

    \n \n \n Default label\n \n
    \n)" }, { "id": "components-checkbox-features--with-leading-visual", "code": "() => {\n return (\n
    \n \n \n \n \n \n Default label\n \n
    \n )\n}" }, { "id": "components-checkbox-features--disabled", "code": "() => {\n return (\n
    \n \n \n Default label\n \n
    \n )\n}" }, { "id": "components-checkbox-features--with-caption", "code": "() => {\n return (\n
    \n \n \n Default label\n This is a caption\n \n
    \n )\n}" }, { "id": "components-checkbox-features--indeterminate", "code": "() => {\n const [isIndeterminate, setIsIndeterminate] = useState(true)\n return (\n
    \n \n {\n setIsIndeterminate(!isIndeterminate)\n }}\n checked={false}\n />\n Default label\n \n
    \n )\n}" } ], "importPath": "@primer/react", "props": [ { "name": "checked", "type": "boolean", "defaultValue": "", "description": "Modifies true/false value of the native checkbox" }, { "name": "defaultChecked", "type": "boolean", "defaultValue": "", "description": "Checks the input by default in uncontrolled mode" }, { "name": "disabled", "type": "boolean", "defaultValue": "", "description": "Modifies the native disabled state of the native checkbox" }, { "name": "indeterminate", "type": "boolean", "defaultValue": "false", "description": "Applies an [indeterminate state](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#attr-indeterminate) to the checkbox" }, { "name": "onChange", "type": "(event: React.ChangeEvent) => void", "defaultValue": "", "description": "A callback function that is triggered when the checked state has been changed" }, { "name": "validationStatus", "type": "'error' | 'success'", "defaultValue": "", "description": "Only used to inform ARIA attributes.\nIndividual checkboxes do not have validation styles." }, { "name": "value", "type": "string", "defaultValue": "", "description": "A unique value that is never shown to the user.\nUsed during form submission and to identify which checkbox inputs are selected." }, { "name": "ref", "type": "React.RefObject" }, { "name": "as", "type": "React.ElementType", "defaultValue": "\"input\"" } ], "subcomponents": [] }, "checkbox_group": { "source": "https://github.com/primer/react/tree/main/packages/react/src/CheckboxGroup", "id": "checkbox_group", "name": "CheckboxGroup", "status": "alpha", "a11yReviewed": "2025-01-08", "stories": [ { "id": "components-checkboxgroup--default", "code": "() => (\n \n Choices\n \n \n Choice one\n \n \n \n Choice two\n \n \n \n Choice three\n \n \n)" }, { "id": "components-checkboxgroup-features--visually-hidden-label", "code": "() => (\n \n Choices\n \n \n Choice one\n \n \n \n Choice two\n \n \n \n Choice three\n \n \n)" }, { "id": "components-checkboxgroup-features--with-external-label", "code": "() => (\n <>\n
    \n External label\n
    \n \n \n \n Choice one\n \n \n \n Choice two\n \n \n \n Choice three\n \n \n \n)" }, { "id": "components-checkboxgroup-features--error", "code": "() => (\n \n Choices\n \n \n Choice one\n \n \n \n Choice two\n \n \n \n Choice three\n \n \n Something went wrong\n \n \n)" }, { "id": "components-checkboxgroup-features--success", "code": "() => (\n \n Choices\n \n \n Choice one\n \n \n \n Choice two\n \n \n \n Choice three\n \n \n Great job!\n \n \n)" }, { "id": "components-checkboxgroup-features--caption", "code": "() => (\n \n Choices\n Caption\n \n \n Choice one\n \n \n \n Choice two\n \n \n \n Choice three\n \n \n)" } ], "importPath": "@primer/react", "props": [ { "name": "aria-labelledby", "type": "string", "defaultValue": "", "description": "Used when associating the input group with a label other than CheckboxGroup.Label" }, { "name": "children", "type": "CheckboxGroup.Label | CheckboxGroup.Caption | CheckboxGroup.Validation | FormControl", "defaultValue": "", "required": true, "description": "" }, { "name": "disabled", "type": "boolean", "defaultValue": "false", "description": "Whether the input group allows user input" }, { "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." }, { "name": "onChange", "type": "(selected: string[], e?: ChangeEvent) => void", "defaultValue": "", "description": "An onChange handler that gets called when the selection changes" }, { "name": "required", "type": "boolean", "defaultValue": "false", "description": "If true, the user must make a selection before the owning form can be submitted" } ], "subcomponents": [ { "name": "CheckboxGroup.Label", "props": [ { "name": "visuallyHidden", "type": "boolean", "defaultValue": "false", "description": "If true, the fieldset legend will be visually hidden" } ] }, { "name": "CheckboxGroup.Caption", "props": [ { "name": "children", "type": "React.ReactNode", "defaultValue": "", "description": "The caption content" } ] }, { "name": "CheckboxGroup.Validation", "props": [ { "name": "children", "type": "React.ReactNode", "defaultValue": "", "description": "The validation message" }, { "name": "variant", "type": "'error' | 'success'", "defaultValue": "", "required": true, "description": "Changes the visual style to match the validation status" } ] } ] }, "circle_badge": { "source": "https://github.com/primer/react/tree/main/packages/react/src/CircleBadge", "id": "circle_badge", "name": "CircleBadge", "status": "deprecated", "a11yReviewed": "2025-01-08", "stories": [ { "id": "deprecated-components-circlebadge--default", "code": "() => (\n \n \n \n)" } ], "importPath": "@primer/react", "props": [ { "name": "variant", "type": "'small' | 'medium' | 'large'", "defaultValue": "'medium'", "description": "Creates a smaller or larger badge. Has no effect if the `size` prop is set" }, { "name": "size", "type": "number", "defaultValue": "", "description": "Sets the size of the badge in pixels. Overrides the `variant` prop when set" }, { "name": "inline", "type": "boolean", "defaultValue": "false", "description": "Styles the badge to `display: inline`" }, { "name": "ref", "type": "React.RefObject" }, { "name": "as", "type": "React.ElementType", "defaultValue": "\"div\"" } ], "subcomponents": [ { "name": "CircleBadge.Icon", "props": [ { "name": "as", "type": "React.ElementType", "defaultValue": "Octicon" } ], "passthrough": { "element": "Octicon", "url": "/Octicon" } } ] }, "confirmationdialog": { "source": "https://github.com/primer/react/tree/main/packages/react/src/ConfirmationDialog", "id": "confirmationdialog", "docsId": "confirmationdialog", "name": "ConfirmationDialog", "status": "alpha", "a11yReviewed": "2025-01-08", "importPath": "@primer/react", "stories": [ { "id": "components-confirmationdialog--default", "code": "() => {\n const [isOpen, setIsOpen] = useState(false)\n const buttonRef = useRef(null)\n const onDialogClose = useCallback(() => setIsOpen(false), [])\n return (\n <>\n \n {isOpen && (\n \n Deleting the universe could have disastrous effects, including but not\n limited to destroying all life on Earth.\n \n )}\n \n )\n}" }, { "id": "components-confirmationdialog-features--shorthand-hook", "code": "() => {\n const confirm = useConfirm()\n const onButtonClick = useCallback(\n async (event: React.MouseEvent) => {\n if (\n (await confirm({\n title: 'Are you sure?',\n content: 'Do you really want to turn this button green?',\n })) &&\n event.target instanceof HTMLElement\n ) {\n event.target.style.color = 'var(--fgColor-success)'\n event.target.textContent = \"I'm green!\"\n }\n },\n [confirm],\n )\n return (\n
    \n \n \n \n \n
    \n )\n}" }, { "id": "components-confirmationdialog-features--shorthand-hook-from-action-menu", "code": "() => {\n const confirm = useConfirm()\n const [text, setText] = useState('open me')\n const onButtonClick = useCallback(async () => {\n if (\n await confirm({\n title: 'Are you sure?',\n content: 'Do you really want to do a trick?',\n })\n ) {\n setText('tada!')\n }\n }, [confirm])\n return (\n
    \n \n {text}\n \n \n \n Do a trick!\n \n \n \n \n
    \n )\n}" }, { "id": "components-confirmationdialog-features--loading-states", "code": "() => {\n const [isOpen, setIsOpen] = useState(false)\n const [isConfirmLoading, setIsConfirmLoading] = useState(false)\n const [isCancelLoading, setIsCancelLoading] = useState(false)\n const handleConfirm = useCallback(() => {\n setIsConfirmLoading(true)\n // Simulate async operation\n setTimeout(() => {\n setIsConfirmLoading(false)\n setIsOpen(false)\n }, 2000)\n }, [])\n const handleCancel = useCallback(() => {\n setIsCancelLoading(true)\n // Simulate async operation\n setTimeout(() => {\n setIsCancelLoading(false)\n setIsOpen(false)\n }, 1500)\n }, [])\n const handleClose = useCallback(\n (gesture: 'confirm' | 'close-button' | 'cancel' | 'escape') => {\n if (gesture === 'confirm') {\n handleConfirm()\n } else if (gesture === 'cancel') {\n handleCancel()\n } else {\n setIsOpen(false)\n }\n },\n [handleConfirm, handleCancel],\n )\n return (\n
    \n \n {isOpen && (\n \n This action cannot be undone. The file will be permanently deleted\n from your repository.\n \n )}\n
    \n )\n}" } ], "props": [ { "name": "onClose", "type": "(gesture: 'confirm' | 'close-button' | 'cancel' | 'escape') => void", "required": true, "description": "This callback is invoked when a gesture to close the dialog is performed. The first argument indicates the gesture." }, { "name": "title", "type": "React.ReactNode", "required": true, "description": "The title of the ConfirmationDialog. This is usually a brief question." }, { "name": "cancelButtonContent", "type": "React.ReactNode", "defaultValue": "Cancel", "description": "The text to use for the cancel button." }, { "name": "confirmButtonContent", "type": "React.ReactNode", "defaultValue": "OK", "description": "The text to use for the confirm button." }, { "name": "confirmButtonType", "type": "'normal' | 'primary' | 'danger'", "defaultValue": "normal", "description": "The type of button to use for the confirm button." }, { "name": "overrideButtonFocus", "type": "'confirm' | 'cancel'", "description": "The button that should be initially focused when the dialog is opened. By default, the initial button focus is the confirm button, unless the confirm button is dangerous, in which case the cancel button is focused. This prop should be used rarely, as it can allow dangerous actions to be taken accidentally." }, { "name": "className", "type": "string", "description": "Additional class names to apply to the dialog." }, { "name": "width", "type": "'small' | 'medium' | 'large' | 'xlarge'", "defaultValue": "medium", "description": "The width of the dialog.\nsmall: 296px\nmedium: 320px\nlarge: 480px\nxlarge: 640px" }, { "name": "height", "type": "'small' | 'large' | 'auto'", "description": "The height of the dialog.\nsmall: 480px\nlarge: 640px\nauto: variable based on contents" } ] }, "counter_label": { "source": "https://github.com/primer/react/tree/main/packages/react/src/CounterLabel", "id": "counter_label", "name": "CounterLabel", "status": "alpha", "a11yReviewed": "2025-01-08", "stories": [ { "id": "components-counterlabel--default", "code": "() => 12" }, { "id": "components-counterlabel-features--primary-theme", "code": "() => 12" }, { "id": "components-counterlabel-features--secondary-theme", "code": "() => 12" } ], "importPath": "@primer/react", "props": [ { "name": "scheme", "type": "'primary' | 'secondary'", "defaultValue": "", "description": "Pass in 'primary' for a darker background and inverse text, or 'secondary' for a lighter background and primary text. Omitting the scheme prop renders the default counter scheme" }, { "name": "className", "type": "string", "description": "Class name(s) for custom styling.", "defaultValue": "" } ], "subcomponents": [] }, "data_table": { "source": "https://github.com/primer/react/tree/main/packages/react/src/DataTable", "id": "data_table", "name": "DataTable", "status": "alpha", "a11yReviewed": "2025-01-08", "stories": [ { "id": "experimental-components-datatable--default", "code": "() => (\n \n \n Repositories\n \n \n A subtitle could appear here to give extra context to the data.\n \n {\n return \n },\n },\n {\n header: 'Updated',\n field: 'updatedAt',\n renderCell: (row) => {\n return \n },\n },\n {\n header: 'Dependabot',\n field: 'securityFeatures.dependabot',\n renderCell: (row) => {\n return row.securityFeatures.dependabot.length > 0 ? (\n \n {row.securityFeatures.dependabot.map((feature) => {\n return \n })}\n \n ) : null\n },\n },\n {\n header: 'Code scanning',\n field: 'securityFeatures.codeScanning',\n renderCell: (row) => {\n return row.securityFeatures.codeScanning.length > 0 ? (\n \n {row.securityFeatures.codeScanning.map((feature) => {\n return \n })}\n \n ) : null\n },\n },\n ]}\n />\n \n)" }, { "id": "experimental-components-datatable-features--with-title", "code": "() => (\n \n \n Repositories\n \n {\n return \n },\n },\n {\n header: 'Updated',\n field: 'updatedAt',\n renderCell: (row) => {\n return \n },\n },\n {\n header: 'Dependabot',\n field: 'securityFeatures.dependabot',\n renderCell: (row) => {\n return row.securityFeatures.dependabot.length > 0 ? (\n \n {row.securityFeatures.dependabot.map((feature) => {\n return \n })}\n \n ) : null\n },\n },\n {\n header: 'Code scanning',\n field: 'securityFeatures.codeScanning',\n renderCell: (row) => {\n return row.securityFeatures.codeScanning.length > 0 ? (\n \n {row.securityFeatures.codeScanning.map((feature) => {\n return \n })}\n \n ) : null\n },\n },\n ]}\n />\n \n)" }, { "id": "experimental-components-datatable-features--with-title-and-subtitle", "code": "() => (\n \n \n Repositories\n \n \n A subtitle could appear here to give extra context to the data.\n \n {\n return \n },\n },\n {\n header: 'Updated',\n field: 'updatedAt',\n renderCell: (row) => {\n return \n },\n },\n {\n header: 'Dependabot',\n field: 'securityFeatures.dependabot',\n renderCell: (row) => {\n return row.securityFeatures.dependabot.length > 0 ? (\n \n {row.securityFeatures.dependabot.map((feature) => {\n return \n })}\n \n ) : null\n },\n },\n {\n header: 'Code scanning',\n field: 'securityFeatures.codeScanning',\n renderCell: (row) => {\n return row.securityFeatures.codeScanning.length > 0 ? (\n \n {row.securityFeatures.codeScanning.map((feature) => {\n return \n })}\n \n ) : null\n },\n },\n ]}\n />\n \n)" }, { "id": "experimental-components-datatable-features--with-sorting", "code": "() => {\n const rows = Array.from(data).sort((a, b) => {\n return b.updatedAt - a.updatedAt\n })\n return (\n \n \n Repositories\n \n \n A subtitle could appear here to give extra context to the data.\n \n {\n return \n },\n },\n {\n header: 'Updated',\n field: 'updatedAt',\n sortBy: 'datetime',\n renderCell: (row) => {\n return \n },\n },\n {\n header: 'Dependabot',\n field: 'securityFeatures.dependabot',\n renderCell: (row) => {\n return row.securityFeatures.dependabot.length > 0 ? (\n \n {row.securityFeatures.dependabot.map((feature) => {\n return \n })}\n \n ) : null\n },\n },\n {\n header: 'Code scanning',\n field: 'securityFeatures.codeScanning',\n renderCell: (row) => {\n return row.securityFeatures.codeScanning.length > 0 ? (\n \n {row.securityFeatures.codeScanning.map((feature) => {\n return \n })}\n \n ) : null\n },\n },\n ]}\n initialSortColumn=\"updatedAt\"\n initialSortDirection=\"DESC\"\n />\n \n )\n}" }, { "id": "experimental-components-datatable-features--with-actions", "code": "() => (\n \n \n Repositories\n \n \n \n \n \n \n \n A subtitle could appear here to give extra context to the data.\n \n {\n return \n },\n },\n {\n header: 'Updated',\n field: 'updatedAt',\n renderCell: (row) => {\n return \n },\n },\n {\n header: 'Dependabot',\n field: 'securityFeatures.dependabot',\n renderCell: (row) => {\n return row.securityFeatures.dependabot.length > 0 ? (\n \n {row.securityFeatures.dependabot.map((feature) => {\n return \n })}\n \n ) : null\n },\n },\n {\n header: 'Code scanning',\n field: 'securityFeatures.codeScanning',\n renderCell: (row) => {\n return row.securityFeatures.codeScanning.length > 0 ? (\n \n {row.securityFeatures.codeScanning.map((feature) => {\n return \n })}\n \n ) : null\n },\n },\n ]}\n />\n \n)" }, { "id": "experimental-components-datatable-features--with-action", "code": "() => (\n \n \n Repositories\n \n \n \n \n \n \n A subtitle could appear here to give extra context to the data.\n \n {\n return \n },\n },\n {\n header: 'Updated',\n field: 'updatedAt',\n renderCell: (row) => {\n return \n },\n },\n {\n header: 'Dependabot',\n field: 'securityFeatures.dependabot',\n renderCell: (row) => {\n return row.securityFeatures.dependabot.length > 0 ? (\n \n {row.securityFeatures.dependabot.map((feature) => {\n return \n })}\n \n ) : null\n },\n },\n {\n header: 'Code scanning',\n field: 'securityFeatures.codeScanning',\n renderCell: (row) => {\n return row.securityFeatures.codeScanning.length > 0 ? (\n \n {row.securityFeatures.codeScanning.map((feature) => {\n return \n })}\n \n ) : null\n },\n },\n ]}\n />\n \n)" }, { "id": "experimental-components-datatable-features--with-row-action", "code": "() => (\n \n \n Repositories\n \n \n A subtitle could appear here to give extra context to the data.\n \n {\n return \n },\n },\n {\n header: 'Updated',\n field: 'updatedAt',\n renderCell: (row) => {\n return \n },\n },\n {\n header: 'Dependabot',\n field: 'securityFeatures.dependabot',\n renderCell: (row) => {\n return row.securityFeatures.dependabot.length > 0 ? (\n \n {row.securityFeatures.dependabot.map((feature) => {\n return \n })}\n \n ) : null\n },\n },\n {\n header: 'Code scanning',\n field: 'securityFeatures.codeScanning',\n renderCell: (row) => {\n return row.securityFeatures.codeScanning.length > 0 ? (\n \n {row.securityFeatures.codeScanning.map((feature) => {\n return \n })}\n \n ) : null\n },\n },\n {\n id: 'actions',\n header: () => Actions,\n renderCell: (row) => {\n return (\n {\n action('Download')(row)\n }}\n />\n )\n },\n },\n ]}\n />\n \n)" }, { "id": "experimental-components-datatable-features--with-row-actions", "code": "() => (\n \n \n Repositories\n \n \n A subtitle could appear here to give extra context to the data.\n \n {\n return \n },\n },\n {\n header: 'Updated',\n field: 'updatedAt',\n renderCell: (row) => {\n return \n },\n },\n {\n header: 'Dependabot',\n field: 'securityFeatures.dependabot',\n renderCell: (row) => {\n return row.securityFeatures.dependabot.length > 0 ? (\n \n {row.securityFeatures.dependabot.map((feature) => {\n return \n })}\n \n ) : null\n },\n },\n {\n header: 'Code scanning',\n field: 'securityFeatures.codeScanning',\n renderCell: (row) => {\n return row.securityFeatures.codeScanning.length > 0 ? (\n \n {row.securityFeatures.codeScanning.map((feature) => {\n return \n })}\n \n ) : null\n },\n },\n {\n id: 'actions',\n header: () => Actions,\n renderCell: (row) => {\n return (\n <>\n {\n action('Edit')(row)\n }}\n />\n {\n action('Delete')(row)\n }}\n />\n \n )\n },\n },\n ]}\n />\n \n)" }, { "id": "experimental-components-datatable-features--with-row-action-menu", "code": "() => (\n \n \n Repositories\n \n \n A subtitle could appear here to give extra context to the data.\n \n {\n return \n },\n },\n {\n header: 'Updated',\n field: 'updatedAt',\n renderCell: (row) => {\n return \n },\n },\n {\n header: 'Dependabot',\n field: 'securityFeatures.dependabot',\n renderCell: (row) => {\n return row.securityFeatures.dependabot.length > 0 ? (\n \n {row.securityFeatures.dependabot.map((feature) => {\n return \n })}\n \n ) : null\n },\n },\n {\n header: 'Code scanning',\n field: 'securityFeatures.codeScanning',\n renderCell: (row) => {\n return row.securityFeatures.codeScanning.length > 0 ? (\n \n {row.securityFeatures.codeScanning.map((feature) => {\n return \n })}\n \n ) : null\n },\n },\n {\n id: 'actions',\n header: () => Actions,\n renderCell: (row) => {\n return (\n \n \n \n \n \n \n {\n action('Copy')(row)\n }}\n >\n Copy row\n \n Edit row\n Export row as CSV\n \n \n Delete row\n \n \n \n \n )\n },\n },\n ]}\n />\n \n)" }, { "id": "experimental-components-datatable-features--with-custom-heading", "code": "() => (\n <>\n \n Security coverage\n \n

    \n Organization members can only see data for the most recently-updated\n repositories. To see all repositories, talk to your organization\n administrator about becoming a security manager.\n

    \n \n {\n return \n },\n },\n {\n header: 'Updated',\n field: 'updatedAt',\n renderCell: (row) => {\n return \n },\n },\n {\n header: 'Dependabot',\n field: 'securityFeatures.dependabot',\n renderCell: (row) => {\n return row.securityFeatures.dependabot.length > 0 ? (\n \n {row.securityFeatures.dependabot.map((feature) => {\n return \n })}\n \n ) : null\n },\n },\n {\n header: 'Code scanning',\n field: 'securityFeatures.codeScanning',\n renderCell: (row) => {\n return row.securityFeatures.codeScanning.length > 0 ? (\n \n {row.securityFeatures.codeScanning.map((feature) => {\n return \n })}\n \n ) : null\n },\n },\n ]}\n />\n \n \n)" }, { "id": "experimental-components-datatable-features--with-no-content", "code": "() => {\n const exampleEmptyData: Array = []\n return exampleEmptyData.length === 0 ? (\n \n \n \n \n Blankslate heading\n \n Use it to provide information when no dynamic content exists.\n \n \n Primary action\n \n \n Secondary action link\n \n \n ) : (\n \n \n Repositories\n \n \n A subtitle could appear here to give extra context to the data.\n \n {\n return \n },\n },\n {\n header: 'Updated',\n field: 'updatedAt',\n renderCell: (row) => {\n return \n },\n },\n {\n header: 'Dependabot',\n field: 'securityFeatures.dependabot',\n renderCell: (row) => {\n return row.securityFeatures.dependabot.length > 0 ? (\n \n {row.securityFeatures.dependabot.map((feature) => {\n return \n })}\n \n ) : null\n },\n },\n {\n header: 'Code scanning',\n field: 'securityFeatures.codeScanning',\n renderCell: (row) => {\n return row.securityFeatures.codeScanning.length > 0 ? (\n \n {row.securityFeatures.codeScanning.map((feature) => {\n return \n })}\n \n ) : null\n },\n },\n ]}\n />\n \n )\n}" }, { "id": "experimental-components-datatable-features--with-loading", "code": "() => {\n const [loading] = React.useState(true)\n return (\n \n \n Repositories\n \n \n A subtitle could appear here to give extra context to the data.\n \n {loading ? (\n \n ) : (\n \n )}\n \n )\n}" }, { "id": "experimental-components-datatable-features--with-pagination", "code": "() => {\n const pageSize = 10\n const [pageIndex, setPageIndex] = React.useState(0)\n const start = pageIndex * pageSize\n const end = start + pageSize\n const rows = repos.slice(start, end)\n return (\n \n \n Repositories\n \n \n A subtitle could appear here to give extra context to the data.\n \n {\n return \n },\n },\n {\n header: 'Updated',\n field: 'updatedAt',\n renderCell: (row) => {\n return \n },\n },\n {\n header: 'Dependabot',\n field: 'securityFeatures.dependabot',\n renderCell: (row) => {\n return row.securityFeatures.dependabot.length > 0 ? (\n \n {row.securityFeatures.dependabot.map((feature) => {\n return \n })}\n \n ) : null\n },\n },\n {\n header: 'Code scanning',\n field: 'securityFeatures.codeScanning',\n renderCell: (row) => {\n return row.securityFeatures.codeScanning.length > 0 ? (\n \n {row.securityFeatures.codeScanning.map((feature) => {\n return \n })}\n \n ) : null\n },\n },\n ]}\n />\n {\n setPageIndex(pageIndex)\n }}\n />\n \n )\n}" } ], "importPath": "@primer/react/experimental", "props": [ { "name": "aria-describedby", "type": "string", "description": "Provide an id to an element which uniquely describes this table" }, { "name": "aria-labelledby", "type": "string", "description": "Provide an id to an element which uniquely labels this table" }, { "name": "data", "type": "Array", "description": "Provide a collection of the rows which will be rendered inside of the table" }, { "name": "columns", "type": "Array>", "description": "Provide the columns for the table and the fields in `data` to which they correspond" }, { "name": "cellPadding", "type": "'condensed' | 'normal' | 'spacious'", "description": "Specify the amount of space that should be available around the contents of a cell" }, { "name": "aria-describedby", "type": "string", "required": false, "description": "Provide an id to an element which uniquely describes this table", "defaultValue": "" }, { "name": "aria-labelledby", "type": "string", "required": false, "description": "Provide an id to an element which uniquely labels this table", "defaultValue": "" }, { "name": "initialSortColumn", "type": "string | number", "required": false, "description": "Provide the id or field of the column by which the table is sorted. When\nusing this `prop`, the input data must be sorted by this column in\nascending order", "defaultValue": "" }, { "name": "initialSortDirection", "type": "'ASC' | 'DESC'", "required": false, "description": "Provide the sort direction that the table should be sorted by on the\ncurrently sorted column", "defaultValue": "" }, { "name": "externalSorting", "type": "boolean", "required": false, "description": "Indicate whether the sorting of the table is managed externally. When `true`, the table will not sort the data internally when a column header is clicked. The `onToggleSort` callback will still be invoked when a column header is clicked.", "defaultValue": "false" }, { "name": "onToggleSort", "type": "(columnId: ObjectPaths | string | number, direction: 'ASC' | 'DESC') => void", "required": false, "description": "Fires every time the user clicks a sortable column header. It reports the column id that is now sorted and the direction after the toggle (never 'NONE').", "defaultValue": "" } ], "subcomponents": [ { "name": "Table", "props": [ { "name": "aria-describedby", "type": "string", "description": "Provide an id to an element which uniquely describes this table" }, { "name": "aria-labelledby", "type": "string", "description": "Provide an id to an element which uniquely labels this table" }, { "name": "children", "type": "React.ReactNode" }, { "name": "cellPadding", "type": "'condensed' | 'normal' | 'spacious'", "description": "Specify the amount of space that should be available around the contents of a cell" } ] }, { "name": "Table.Head", "props": [ { "name": "children", "type": "React.ReactNode" } ] }, { "name": "Table.Actions", "props": [ { "name": "children", "type": "React.ReactNode" } ] }, { "name": "Table.Body", "props": [ { "name": "children", "type": "React.ReactNode" } ] }, { "name": "Table.Row", "props": [ { "name": "children", "type": "React.ReactNode" } ] }, { "name": "Table.Header", "props": [ { "name": "align", "type": "'end' | 'start'", "required": false, "description": "The horizontal alignment of the cell's content", "defaultValue": "" }, { "name": "children", "type": "React.ReactNode" } ] }, { "name": "Table.Cell", "props": [ { "name": "align", "type": "'end' | 'start'", "required": false, "description": "The horizontal alignment of the cell's content", "defaultValue": "" }, { "name": "children", "type": "React.ReactNode" }, { "name": "scope", "type": "'row'", "description": "Provide the scope for a table cell, useful for defining a row header using `scope=\"row\"`" } ] }, { "name": "Table.CellPlaceholder", "props": [] }, { "name": "Table.Container", "props": [ { "name": "children", "type": "React.ReactNode" } ] }, { "name": "Table.Divider", "props": [] }, { "name": "Table.Title", "props": [ { "name": "children", "type": "React.ReactNode" }, { "name": "id", "type": "string", "required": true, "description": "Provide a unique id for the table subtitle. This should be used along with\n`aria-labelledby` on `DataTable`" } ] }, { "name": "Table.Subtitle", "props": [ { "name": "children", "type": "React.ReactNode" }, { "name": "id", "type": "string", "required": true, "description": "Provide a unique id for the table subtitle. This should be used along with\n`aria-describedby` on `DataTable`" } ] }, { "name": "Table.Skeleton", "props": [ { "name": "cellPadding", "type": "'condensed' | 'normal' | 'spacious'", "description": "Specify the amount of space that should be available around the contents of a cell", "defaultValue": "normal" }, { "name": "columns", "required": true, "type": "Array>" }, { "name": "rows", "type": "number", "description": "Optionally specify the number of rows which should be included in the skeleton state of the component", "defaultValue": "10" } ] }, { "name": "Table.Pagination", "props": [ { "name": "aria-label", "type": "string", "required": true, "description": "Defines a string value that labels the current element.\nProvide a label for the navigation landmark rendered by this component\n@see aria-labelledby." }, { "name": "defaultPageIndex", "type": "string", "description": "Provide an optional index to specify the default selected page" }, { "name": "id", "type": "string", "description": "Optionally provide an `id` that is placed on the navigation landmark\nrendered by this component" }, { "name": "onChange", "type": "({ pageIndex }: { pageIndex: number }) => void", "description": "Optionally provide a handler that is called whenever the pagination state\nis updated" }, { "name": "pageSize", "type": "number", "description": "Optionally specify the number of items within a page", "defaultValue": "25" }, { "name": "totalCount", "type": "number", "required": true, "description": "Specify the total number of items within the collection" }, { "name": "showPages", "type": "boolean | { narrow?: boolean; regular?: boolean; wide?: boolean; }", "required": false, "description": "Whether to show the page numbers", "defaultValue": "{narrow: false}" } ] }, { "name": "Table.ErrorDialog", "props": [ { "name": "children", "required": true, "type": "React.ReactNode", "description": "The content of the dialog. This is usually a message explaining the error." }, { "name": "title", "type": "string", "defaultValue": "'Error'", "description": "The title of the dialog. This is usually a short description of the error." }, { "name": "onRetry", "type": "() => void", "description": "Event handler called when the user clicks the retry button." }, { "name": "onDismiss", "type": "() => void", "description": "Event handler called when the dialog is dismissed." } ] }, { "name": "Table.SortHeader", "props": [ { "name": "direction", "type": "'ASC' | 'DESC' | 'NONE'", "required": true, "description": "Specify the sort direction for the TableHeader", "defaultValue": "" }, { "name": "onToggleSort", "type": "() => void", "required": true, "description": "Provide a handler that is called when the sortable TableHeader is\ninteracted with via a click or keyboard interaction", "defaultValue": "" }, { "name": "align", "type": "'end' | 'start'", "description": "The horizontal alignment of the cell's content", "defaultValue": "" } ] }, { "name": "Column options", "props": [ { "name": "align", "type": "'start' | 'end'", "description": "The horizontal alignment of the column's content" }, { "name": "field", "type": "ObjectPaths", "description": "Optionally provide a field to render for this column. This may be the key of the object or a string that accesses nested objects through `.`. For example: `field: a.b.c`\nAlternatively, you may provide a `renderCell` for this column to render the field in a row" }, { "name": "header", "type": "string | (() => React.ReactNode)", "required": true, "description": "Provide the name of the column. This will be rendered as a table header within the table itself" }, { "name": "maxWidth", "type": "React.CSSProperties['maxWidth']", "description": "The maximum width the column can grow to" }, { "name": "minWidth", "type": "React.CSSProperties['minWidth']", "description": "The minimum width the column can grow to" }, { "name": "renderCell", "type": "(data: Data) => React.ReactNode", "description": "Provide a custom component or render prop to render the data for this column in a row" }, { "name": "rowHeader", "type": "boolean", "description": "Specify if the value of this column for a row should be treated as a row header" }, { "name": "sortBy", "type": "boolean | 'alphanumeric' | 'basic' | 'datetime' | (a: Data, b: Data) => number", "description": "Specify if the table should sort by this column and, if applicable, a specific sort strategy or custom sort strategy" }, { "name": "width", "defaultValue": "'grow'", "type": "'grow' | 'growCollapse' | 'auto' | React.CSSProperties['width']", "description": "Controls the width of the column.\n\n- 'grow': Stretch to fill available space, and min width is the width of the widest cell in the column\n- 'growCollapse': Stretch to fill available space or shrink to fit in the available space. Allows the column to shrink smaller than the cell content's width.\n- 'auto': The column is the width of it’s widest cell. Not intended for use with columns who’s content length varies a lot because a layout shift will occur when the content changes\n- explicit width: Will be exactly that width and will not grow or shrink to fill the parent" } ] } ] }, "details": { "source": "https://github.com/primer/react/tree/main/packages/react/src/Details", "id": "details", "name": "Details", "status": "alpha", "a11yReviewed": "2025-01-08", "stories": [ { "id": "components-details--default", "code": "() => {\n const { getDetailsProps } = useDetails({\n closeOnOutsideClick: true,\n })\n return (\n
    \n See Details\n This is some content\n
    \n )\n}" } ], "importPath": "@primer/react", "props": [], "subcomponents": [ { "name": "Details.Summary", "props": [ { "name": "as", "type": "React.ElementType>", "defaultValue": "summary", "required": false, "description": "HTML element to render summary as." }, { "name": "children", "type": "React.ReactNode" } ] } ] }, "dialog_v2": { "source": "https://github.com/primer/react/tree/main/packages/react/src/Dialog", "id": "dialog_v2", "docsId": "dialog", "name": "Dialog", "status": "alpha", "a11yReviewed": "2025-01-08", "stories": [ { "id": "components-dialog--default", "code": "() => {\n const [isOpen, setIsOpen] = useState(false)\n const [secondOpen, setSecondOpen] = useState(false)\n const buttonRef = useRef(null)\n const onDialogClose = useCallback(() => setIsOpen(false), [])\n const onSecondDialogClose = useCallback(() => setSecondOpen(false), [])\n const openSecondDialog = useCallback(() => setSecondOpen(true), [])\n return (\n <>\n \n {isOpen && (\n \n {lipsum}\n {secondOpen && (\n \n Hello world\n \n )}\n \n )}\n \n )\n}" }, { "id": "components-dialog-features--with-custom-renderers", "code": "({ width, height, subtitle }: DialogStoryProps) => {\n const [isOpen, setIsOpen] = useState(false)\n const onDialogClose = useCallback(() => setIsOpen(false), [])\n return (\n <>\n \n {isOpen && (\n \n {lipsum}\n \n )}\n \n )\n}" }, { "id": "components-dialog-features--stress-test", "code": "({ width, height, subtitle }: DialogStoryProps) => {\n const [isOpen, setIsOpen] = useState(false)\n const [secondOpen, setSecondOpen] = useState(false)\n const buttonRef = useRef(null)\n const onDialogClose = useCallback(() => setIsOpen(false), [])\n const onSecondDialogClose = useCallback(() => setSecondOpen(false), [])\n const openSecondDialog = useCallback(() => setSecondOpen(true), [])\n const manyButtons = new Array(7).fill(undefined).map((_, i) => ({\n content: `Button ${i}`,\n }))\n return (\n <>\n \n {isOpen && (\n \n {lipsum}\n {secondOpen && (\n \n Hello world\n \n )}\n \n )}\n \n )\n}" }, { "id": "components-dialog-features--repro-multistep-dialog-with-conditional-footer", "code": "({ width, height }: DialogStoryProps) => {\n const [isOpen, setIsOpen] = useState(false)\n const onDialogClose = useCallback(() => setIsOpen(false), [])\n const [step, setStep] = React.useState(1)\n const [inputText, setInputText] = React.useState('')\n const dialogRef = useRef(null)\n const renderFooterConditionally = () => {\n if (step === 1) return null\n return (\n \n \n \n )\n }\n React.useEffect(() => {\n // focus the close button when the step changes\n const focusTarget = dialogRef.current?.querySelector(\n 'button[aria-label=\"Close\"]',\n ) as HTMLButtonElement\n if (step === 2) {\n focusTarget.focus()\n }\n }, [step])\n return (\n <>\n \n {isOpen && (\n \n {step === 1 ? (\n \n \n Bug Report \n \n \n Feature request{' '}\n \n \n \n ) : (\n
    \n \n \n setInputText(event.target.value)}\n />\n \n
    \n )}\n \n )}\n \n )\n}" }, { "id": "components-dialog-features--bottom-sheet-narrow", "code": "() => {\n const [isOpen, setIsOpen] = useState(true)\n const buttonRef = useRef(null)\n const onDialogClose = useCallback(() => setIsOpen(false), [])\n return (\n <>\n \n {isOpen && (\n \n {bodyContent}\n \n )}\n \n )\n}" }, { "id": "components-dialog-features--full-screen-narrow", "code": "() => {\n const [isOpen, setIsOpen] = useState(true)\n const buttonRef = useRef(null)\n const onDialogClose = useCallback(() => setIsOpen(false), [])\n return (\n <>\n \n {isOpen && (\n \n {bodyContent}\n \n )}\n \n )\n}" }, { "id": "components-dialog-features--side-sheet", "code": "() => {\n const [isOpen, setIsOpen] = useState(true)\n const buttonRef = useRef(null)\n const onDialogClose = useCallback(() => setIsOpen(false), [])\n return (\n <>\n \n {isOpen && (\n \n {bodyContent}\n \n )}\n \n )\n}" }, { "id": "components-dialog-features--return-focus-ref", "code": "() => {\n const [isOpen, setIsOpen] = useState(false)\n const onDialogClose = useCallback(() => setIsOpen(false), [])\n const triggerRef = React.useRef(null)\n const triggerButton = (\n \n )\n if (!isOpen) return triggerButton\n return (\n Show Dialog}>\n {triggerButton}\n \n body\n \n \n )\n}" }, { "id": "components-dialog-features--new-issues", "code": "() => {\n const [isOpen, setIsOpen] = useState(false)\n const onDialogClose = useCallback(() => setIsOpen(false), [])\n const initialFocusRef = useRef(null)\n return (\n <>\n \n {isOpen ? (\n (\n \n \n Item 1\n \n \n Link\n \n \n )}\n >\n ) : null}\n \n )\n}" }, { "id": "components-dialog-features--retains-focus-trap-with-dynamic-content", "code": "() => {\n const [isOpen, setIsOpen] = useState(false)\n const [secondOpen, setSecondOpen] = useState(false)\n const [expandContent, setExpandContent] = useState(false)\n const [changeBodyContent, setChangeBodyContent] = useState(false)\n const buttonRef = useRef(null)\n const onDialogClose = useCallback(() => setIsOpen(false), [])\n const onSecondDialogClose = useCallback(() => setSecondOpen(false), [])\n const openSecondDialog = useCallback(() => setSecondOpen(true), [])\n const renderFooterConditionally = () => {\n if (!changeBodyContent) return null\n return (\n \n \n \n )\n }\n return (\n <>\n \n {isOpen && (\n \n \n \n \n {expandContent && (\n \n {lipsum}\n \n \n \n )}\n {secondOpen && (\n \n Hello world\n \n )}\n \n )}\n \n )\n}" }, { "id": "components-dialog-features--align-top", "code": "() => {\n const [isOpen, setIsOpen] = useState(true)\n const buttonRef = useRef(null)\n const onDialogClose = useCallback(() => setIsOpen(false), [])\n return (\n <>\n \n {isOpen && (\n \n {bodyContent}\n \n )}\n \n )\n}" }, { "id": "components-dialog-features--align-bottom", "code": "() => {\n const [isOpen, setIsOpen] = useState(true)\n const buttonRef = useRef(null)\n const onDialogClose = useCallback(() => setIsOpen(false), [])\n return (\n <>\n \n {isOpen && (\n \n {bodyContent}\n \n )}\n \n )\n}" } ], "importPath": "@primer/react", "props": [ { "name": "title", "type": "React.ReactNode", "description": "Title of the Dialog. Also serves as the aria-label for this Dialog." }, { "name": "subtitle", "type": "React.ReactNode", "description": "The Dialog's subtitle. Optional. Rendered below the title in smaller type with less contrast. Also serves as the aria-describedby for this Dialog." }, { "name": "renderHeader", "type": "React.FunctionComponent>", "description": "Provide a custom renderer for the dialog header. This content is rendered directly into the dialog body area, full bleed from edge to edge, top to the start of the body element. Warning: using a custom renderer may violate Primer UX principles." }, { "name": "renderBody", "type": "React.FunctionComponent>", "description": "Provide a custom render function for the dialog body. This content is rendered directly into the dialog body area, full bleed from edge to edge, header to footer. Warning: using a custom renderer may violate Primer UX principles." }, { "name": "renderFooter", "type": "React.FunctionComponent>", "description": "Provide a custom render function for the dialog footer. This content is rendered directly into the dialog footer area, full bleed from edge to edge, end of the body element to bottom. Warning: using a custom renderer may violate Primer UX principles." }, { "name": "footerButtons", "type": "DialogButtonProps[]", "description": "Specifies the buttons to be rendered in the Dialog footer." }, { "name": "onClose", "type": "(gesture: 'close-button' | 'escape') => void", "description": "This method is invoked when a gesture to close the dialog is used (either an Escape key press or clicking the 'X' in the top-right corner). The gesture argument indicates the gesture that was used to close the dialog (either 'close-button' or 'escape')." }, { "name": "role", "type": "'dialog' | 'alertdialog'", "description": "The ARIA role to assign to this dialog. See [dialog modal](https://www.w3.org/TR/wai-aria-practices-1.1/#dialog_modal) and [alert dialog](https://www.w3.org/TR/wai-aria-practices-1.1/#alertdialog)" }, { "name": "width", "type": "'small' | 'medium' | 'large' | 'xlarge' | string | number", "description": "The width of the dialog.\nsmall: 296px\nmedium: 320px\nlarge: 480px\nxlarge: 640px\n\nAlso accepts any valid CSS width value (e.g. '400px', '80rem') or a number, which is interpreted as a pixel width." }, { "name": "height", "type": "'small' | 'large' | 'auto'", "description": "The height of the dialog.\nsmall: 296x480\nlarge: 480x640\nauto: variable based on contents" }, { "name": "returnFocusRef", "type": "React.RefObject", "describedby": "Return focus to this element when the Dialog closes, instead of the element that had focus immediately before the Dialog opened" }, { "name": "initialFocusRef", "type": "React.RefObject", "description": "Focus this element when the Dialog opens" }, { "name": "position", "type": "'center' | 'left' | 'right' | { narrow: 'center' | 'left' | 'right' | 'bottom' | 'fullscreen', regular: 'center' | 'left' | 'right' | 'bottom' | 'fullscreen', wide: 'center' | 'left' | 'right' | 'bottom' | 'fullscreen' }", "required": false, "description": "The position of the dialog", "defaultValue": "" }, { "name": "align", "type": "'top' | 'center' | 'bottom'", "required": false, "description": "The vertical alignment of the dialog. Only applies when position is 'center' (the default). 'top' positions the Dialog ~4rem from the top of the screen, 'center' (default) vertically centers the Dialog, 'bottom' positions the Dialog near the bottom of the screen.", "defaultValue": "" }, { "name": "className", "type": "string | undefined", "defaultValue": "", "description": "CSS string" }, { "name": "style", "type": "React.CSSProperties | undefined", "defaultValue": "", "description": "React CSS properties" } ], "subcomponents": [ { "name": "Dialog.Body", "props": [] }, { "name": "Dialog.Buttons", "props": [ { "name": "buttons", "type": "DialogButtonProps[] (see table below)", "required": true } ] }, { "name": "Dialog.CloseButton", "props": [ { "name": "onClose", "type": "() => void", "required": true, "description": "Callback for closing the Dialog", "defaultValue": "" } ] }, { "name": "Dialog.Footer", "props": [] }, { "name": "Dialog.Header", "props": [] }, { "name": "Dialog.Title", "props": [] }, { "name": "DialogButtonProps", "props": [ { "name": "buttonType", "type": "'default' | 'danger' | 'primary' | 'normal'", "description": "The variant of Button to use" }, { "name": "content", "type": "React.ReactNode", "required": true, "description": "The Button's inner text" }, { "name": "autoFocus", "type": "boolean", "description": "If true, and if this is the only button with autoFocus set to true, focus this button automatically when the dialog appears." }, { "name": "ref", "type": "React.RefObject", "description": " A reference to the rendered Button’s DOM node, used together with `autoFocus` for `focusTrap`’s `initialFocus`." } ] } ] }, "feature_flags": { "source": "https://github.com/primer/react/tree/main/packages/react/src/FeatureFlags", "id": "feature_flags", "name": "FeatureFlags", "status": "draft", "a11yReviewed": false, "stories": [], "importPath": "@primer/react/experimental", "props": [ { "name": "flags", "type": "FeatureFlags", "required": true, "description": "Object where keys are feature flag names and values are boolean" } ], "subcomponents": [] }, "flash": { "source": "https://github.com/primer/react/tree/main/packages/react/src/Flash", "id": "flash", "name": "Flash", "status": "alpha", "a11yReviewed": "2025-01-08", "stories": [ { "id": "components-flash--default", "code": "() => Default" }, { "id": "components-flash-features--success", "code": "() => (\n \n
    \n \n
    \n
    Success
    \n \n)" }, { "id": "components-flash-features--danger", "code": "() => (\n \n
    \n \n
    \n
    Danger
    \n \n)" }, { "id": "components-flash-features--warning", "code": "() => (\n \n
    \n \n
    \n
    Warning
    \n \n)" }, { "id": "components-flash-features--full", "code": "() => (\n \n
    \n \n
    \n
    Full
    \n \n)" }, { "id": "components-flash-features--with-icon-and-action", "code": "() => (\n \n
    \n \n
    \n
    \n This is a flash message with an icon and an action.\n Learn more.\n
    \n
    \n \n
    \n     \n)" }, { "id": "components-flash-features--with-icon-action-dismiss", "code": "() => (\n \n
    \n \n
    \n
    \n This is a flash message with an icon and an action.\n Learn more.\n
    \n
    \n \n
    \n
    \n \n
    \n     \n)" } ], "importPath": "@primer/react", "props": [ { "name": "full", "type": "boolean", "defaultValue": "false", "description": "Creates a full width Flash component" }, { "name": "variant", "type": "'default' | 'success' | 'warning' | 'danger'", "defaultValue": "'default'", "description": "Sets the background color and border" }, { "name": "ref", "type": "React.RefObject" }, { "name": "as", "type": "React.ElementType", "defaultValue": "\"div\"" } ], "subcomponents": [] }, "form_control": { "source": "https://github.com/primer/react/tree/main/packages/react/src/FormControl", "id": "form_control", "name": "FormControl", "status": "alpha", "a11yReviewed": "2025-01-08", "stories": [ { "id": "components-formcontrol--default", "code": "() => (\n \n Form Input Label\n This is a caption\n \n \n)" }, { "id": "components-formcontrol-features--with-complex-inputs", "code": "() => {\n const [tokens, setTokens] = useState([...mockTokens])\n const onTokenRemove = (tokenId: string | number) => {\n setTokens(\n tokens.filter((token: { id: string | number }) => token.id !== tokenId),\n )\n }\n return (\n
    \n \n \n TextInputWithTokens\n \n \n \n \n \n Autocomplete\n \n \n \n \n \n \n \n \n \n Select\n \n \n \n Textarea\n