\n \n \n Interactive\n \n \n console.log('clicked')} text=\"Button\" />\n console.log('focused')} text=\"Focusable Span\" />\n \n
\n \n \n Interactive with `onRemove` passed\n \n \n {\n console.log('remove me')\n }}\n />\n console.log('clicked')}\n text=\"Button\"\n onRemove={() => {\n console.log('remove me')\n }}\n />\n console.log('focused')}\n text=\"Focusable Span\"\n onRemove={() => {\n console.log('remove me')\n }}\n />\n \n
\n\n```\n\n### IssueLabelToken\n\nTokens that represent Issue labels should use the `IssueLabelToken` component.\n\n```jsx live\n\n \n \n Resting\n \n
\n\n \n \n isSelected\n \n
\n\n \n \n With `onRemove` passed\n \n {\n console.log('remove me')\n }}\n />\n
\n\n \n \n Size options\n \n \n {\n console.log('remove me')\n }}\n />\n {\n console.log('remove me')\n }}\n />\n {\n console.log('remove me')\n }}\n />\n {\n console.log('remove me')\n }}\n />\n \n
\n\n```\n\n### AvatarToken\n\nTokens that represent GitHub users should use the `AvatarToken` component.\n\n\n This component should not be used with the small or medium size\n option\n \n\n```jsx live\n\n \n\n \n\n \n
\n With `onRemove` passed\n \n
{\n console.log('remove me')\n }}\n />\n \n
\n Size options\n \n
\n {\n console.log('remove me')\n }}\n />\n {\n console.log('remove me')\n }}\n />\n \n \n Text with a tooltip \n \n```\n\n## Component props\n\n| Name | Type | Default | Description |\n| :--------- | :---------------- | :-----: | :------------------------------------------------------------------------------------------------------------------ |\n| align | String | | Can be either `left` or `right`. |\n| direction | String | | Can be one of `n`, `ne`, `e`, `se`, `s`, `sw`, `w`, `nw`. Sets where the tooltip renders in relation to the target. |\n| noDelay | Boolean | | When set to `true`, tooltip appears without any delay |\n| aria-label | String | | Text used in `aria-label` (for accessibility). |\n| wrap | Boolean | | Use `true` to allow text within tooltip to wrap. |\n| sx | SystemStyleObject | {} | Style to be applied to the component |\n","parent":{"relativeDirectory":"","name":"Tooltip"}},{"fileAbsolutePath":"/home/runner/work/react/react/docs/content/Truncate.md","frontmatter":{"title":"Truncate"},"rawBody":"---\ncomponentId: truncate\ntitle: Truncate\nstatus: Alpha\n---\n\nThe Truncate component will shorten text with an ellipsis. Always add a `title` attribute to the truncated element so the full text remains accessible.\n\n## Default example\n\nTruncate will prevent text that overflows from wrapping. The default max-width is 125px.\n\n```jsx live\n\n Some text with a branch-name-that-is-really-long\n \n```\n\n## Custom max-width example\n\nYou can override the maximum width of the truncated text with the `maxWidth` prop.\n\n```jsx live\n\n Some text with a branch-name-that-is-really-long\n \n```\n\n## Inline example\n\nYou can use the `inline` boolean prop for inline (or inline-block) elements with a fixed maximum width (default: 125px).\n\n```jsx live\n\n Some text with a branch-name-that-is-really-long\n \n```\n\n## Expandable example\n\nYou can use the `expandable` boolean prop to display the truncated text on hover.\n\n```jsx live\n\n Some text with a branch-name-that-is-really-long\n \n```\n\n## Component props\n\n| Name | Type | Default | Description |\n| :--------- | :---------------- | :-----: | :----------------------------------------------------------- |\n| as | String | `div` | Sets the HTML tag for the component |\n| maxWidth | Number | 125 | Sets the max-width of the text |\n| inline | Boolean | false | displays text as inline block and vertical aligns to the top |\n| expandable | Boolean | false | allows the truncated text to be displayed on hover |\n| sx | SystemStyleObject | {} | Style to be applied to the component |\n","parent":{"relativeDirectory":"","name":"Truncate"}},{"fileAbsolutePath":"/home/runner/work/react/react/docs/content/UnderlineNav.md","frontmatter":{"title":"UnderlineNav"},"rawBody":"---\ncomponentId: underline_nav\ntitle: UnderlineNav\nstatus: Alpha\n---\n\nUse the UnderlineNav component to style navigation with a minimal underlined selected state, typically used for navigation placed at the top of the page.\n\nTo use UnderlineNav with [react-router](https://github.com/ReactTraining/react-router) or\n[react-router-dom](https://www.npmjs.com/package/react-router-dom), pass\n`as={NavLink}` and omit the `selected` prop.\nThis ensures that the NavLink gets `activeClassName='selected'`\n\n**Attention:** Make sure to properly label your `UnderlineNav` with an `aria-label` to provide context about the type of navigation contained in `UnderlineNav`.\n\n## Default example\n\n```jsx live\n\n \n Home\n \n Documentation \n Support \n \n```\n\n## Component props\n\n### UnderlineNav\n\n| Name | Type | Default | Description |\n| :--------- | :---------------- | :-----: | :------------------------------------------------------------------------------------- |\n| actions | Node | | Place another element, such as a button, to the opposite side of the navigation items. |\n| align | String | | Use `right` to have navigation items aligned right. |\n| full | Boolean | | Used to make navigation fill the width of the container. |\n| aria-label | String | | Used to set the `aria-label` on the top level `` element. |\n| sx | SystemStyleObject | {} | Style to be applied to the component |\n\n### UnderlineNav.Link\n\n| Name | Type | Default | Description |\n| :------- | :---------------- | :-----: | :----------------------------------------------- |\n| as | String | | sets the HTML tag for the component |\n| href | String | | URL to be used for the Link |\n| selected | Boolean | | Used to style the link as selected or unselected |\n| sx | SystemStyleObject | {} | Style to be applied to the component |\n","parent":{"relativeDirectory":"","name":"UnderlineNav"}},{"fileAbsolutePath":"/home/runner/work/react/react/docs/content/anchoredPosition.mdx","frontmatter":{"title":"Anchored Position Behavior"},"rawBody":"---\ntitle: Anchored Position Behavior\n---\n\nThe `getAnchoredPosition` behavior and `useAnchoredPosition` hook are used to calculate the position of a \"floating\" element that is anchored to another DOM element. This is useful for implementing overlay UI, such as dialogs, popovers, tooltips, toasts, and dropdown-style menus.\n\nAt a high level, the `getAnchoredPosition` algorithm will attempt to find the most suitable position for the floating element based on the passed-in settings, its containing element, and the size and position of the anchor element. Specifically, the calculated position should try to ensure that the floating element, when positioned at the calculated coordinates, does not overflow or underflow the container's bounding box.\n\nSettings for this behavior allow the user to customize several aspects of this calculation. See **PositionSettings** below for a detailed description of these settings.\n\n### Positioning algorithm\n\nWhen calculating the position of the floating element, the algorithm relies on different measurements from three separate elements:\n\n1. The floating element's width and height\n2. The anchor element's x/y position and its width and height\n3. The floating element's clipping container (for x/y position, width and height, and border sizes)\n\nThe public API only asks for the first two elements; the floating element's container is discovered via DOM traversal.\n\n#### Finding the floating element's clipping container\n\nThe returned anchored position calculation is relative to the floating element's closest [_positioned_](https://developer.mozilla.org/en-US/docs/Web/CSS/position#types_of_positioning) ancestor. To find this ancestor, we try to check parents of the floating element until we find one that has a position set to anything other than `static` and use that element's bounding box as the container. If we can't find such an element, we will try to use `document.body`.\n\nOnce we have found the appropriate relative ancestor, we attempt to find the floating element's _clipping container_. The clipping container is an element that: 1) has `overflow` set to something other than `visible`, and 2) is either an ancestor of the relative ancestor, or is itself the relative ancestor. Again, if we cannot locate such an element, we will use `document.body` as the clipping container.\n\nOnce we have the clipping container, its bounding box is used as the viewport for the position calculation (see the next section). If the clipping container ends up being `document.body`, we take one additional step, allowing the clipping rectangle to be at least as tall as the window. This is done because the `body` element doesn't take up the full window size by default, but we still want to allow the entire space to be used as the viewport for the position calculation. It may be a good idea to ensure that this clipping container element _also_ contains the anchor element and is scrollable. This will ensure that if scrolled, the anchor and floating element will move together.\n\n#### Positioning and overflow\n\nWith the positions and sizes of the above DOM elements, the algorithm calculates the (x, y) coordinate for the floating element. Then, it checks to see if, based on the floating element's size, if it would overflow the bounds of the container. If it would, it does one of two things:\n\nA) If the overflow happens in the same direction as the anchor side (e.g. side is `'outside-bottom'` and the overflowing portion of the floating element is the bottom), try to find a different side, recalculate the position, and check for overflow again. If we check all four sides and don't find one that fits, revert to the bottom side, in hopes that a scrollbar might appear.\nB) Otherwise, adjust the alignment offset so that the floating element can stay inside the container's bounds.\n\nFor a more in-depth explanation of the positioning settings, see `PositionSettings` below.\n\n### Demo\n\nDeploy Storybook to see a live demo of `anchoredPosition`.\n\n### Usage\n\n```ts\nconst settings = {\n side: 'outside-right',\n align: 'center',\n alignmentOffset: 10,\n anchorOffset: -10\n} as Partial\nconst float = document.getElementById('floatingElement')\nconst anchor = document.getElementById('anchorElement')\nconst {top, left} = getAnchoredPosition(float, anchor, settings)\nfloat.style.top = `${top}px`\nfloat.style.left = `${left}px`\n```\n\n### API\n\nThe `getAnchoredPosition` function takes the following arguments.\n\n| Name | Type | Default | Description |\n| :-------------- | :----------------- | :-----: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| floatingElement | `Element` | | This is an Element that is currently rendered on the page. `getAnchoredPosition` needs to be able to measure this element's `width` and `height`. |\n| anchorElement | `Element` | | This is an Element that the floating element will be \"anchored\" to. In other words, the calculated position of the floating element will be based on this element's position and size. |\n| settings | `PositionSettings` | `{}` | Settings to customize the positioning algorithm. See below for a description of each setting. |\n\n#### PositionSettings interface\n\n`PositionSettings` is an object with the following interface\n\n| Name | Type | Default | Description |\n| :--------------- | :---------------- | :----------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| side | `AnchorSide` | `\"outside-bottom\"` | Sets the side of the anchor element that the floating element should be pinned to. This side is given by a string starting with either `inside` or `outside`, followed by a hyphen, followed by either `top`, `right`, `bottom`, or `left`. Additionally, `\"inside-center\"` is an allowed value.\n }\n >\n Floating element\n \n }>\n Anchor Element\n \n
\n )\n}\n```\n\n### useAnchoredPosition hook\n\n| Name | Type | Default | Description |\n| :----------- | :----------------------------- | :-------: | :------------------------------------------------------------------------------------------------------------------- |\n| settings | `AnchoredPositionHookSettings` | undefined | Optional settings to control how the anchored position is calculated. See below. |\n| dependencies | `React.DependencyList` | undefined | Dependencies to determine when to re-calculate the position. If undefined or `[]`, only calculate the position once. |\n\n**Return value**\n\n| Name | Type | Description |\n| :----------------- | :---------------------------- | :------------------------------------------------- |\n| floatingElementRef | `React.RefObject` | This ref must be added to the floating element JSX |\n| anchorElementRef | `React.RefObject` | This ref must be added to the anchor element JSX |\n| position | `{top: number, left: number}` | The calculated position |\n\n### AnchoredPositionHookSettings interface\n\n`AnchoredPositionHookSettings` is an object with an interface that extends `PositionSettings` (see above). Additionally, it adds the following properties:\n\n| Name | Type | Default | Description |\n| :----------------- | :----------------------------- | :---------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| floatingElementRef | `React.RefObject` | `undefined` | If provided, this will be the ref used to access the element that will be used for the floating element. Its size measurements are needed by the underlying `useAnchoredPosition` behavior. Otherwise, this hook will create the ref for you and return it. In both cases, the ref must be provided to the floating element's JSX. |\n| anchorElementRef | `React.RefObject` | `undefined` | If provided, this will be the ref used to access the element that will be used for the anchor element. Its position and size measurements are needed by the underlying `useAnchoredPosition` behavior. Otherwise, this hook will create the ref for you and return it. In both cases, the ref must be provided to the anchor element's JSX. |\n","parent":{"relativeDirectory":"","name":"anchoredPosition"}},{"fileAbsolutePath":"/home/runner/work/react/react/docs/content/core-concepts.md","frontmatter":{"title":"Core Concepts"},"rawBody":"---\ntitle: Core Concepts\n---\n\nThis document aims to discuss some of the core concepts of building with Primer React.\n\n## Responsive props\n\nIt's really easy to set different values for most of our component props based on screen size! We take advantage of [styled-system](https://github.com/styled-system/styled-system)'s responsive props API in our components.\n\n```\n\n```\n\n## Providing your own theme\n\nYou can provide your own theme to Primer React! There are a few ways of doing this to varying degrees, checkout the [theme docs](https://primer.style/components/primer-theme) for more information.\n\n## The `css` prop\n\nWhen push comes to shove and you just _really_ need to add a custom CSS rule, you can do that with the `css` prop. Please don't abuse this :)\n\n```\nHello \n```\n\nThis will allow you to use all of the `Button` props _and_ all of the `Box` props without having to wrap your `Button` component in another `Box` component.\n\n**This pattern does have some limitations.** Usage of the `as` prop can lead to unexpected output. In the example above, if the user had done `` instead, because the `Box`'s render method is ultimately applied, and `Box` components render `div`'s, you'll see that the rendered component is a `div` when ideally you'd like it to be a `button`. It is also not always clear how the styles in both components will interact and/or override each other.\n\nFor these reasons, **we recommend only using the `as` prop when you cannot achieve the same result by nesting components.** The `Box` / `Button` example could be done like so:\n\n```.jsx\n\n Hi \n \n```\n","parent":{"relativeDirectory":"","name":"core-concepts"}},{"fileAbsolutePath":"/home/runner/work/react/react/docs/content/focusTrap.mdx","frontmatter":{"title":"Focus Trap Behavior"},"rawBody":"---\ntitle: Focus Trap Behavior\n---\n\nThe `focusTrap` behavior and `useFocusTrap` hook are used prevent focus from leaving a particular element. This is useful for implementing modal dialogs: only the content within the dialog should be interactive, even though the UI underneath may still be visible.\n\n### Behavior\n\n- Activation: As soon as the focus trap is activated, it will ensure that an element within the container has focus. If it doesn't, it will focus the first focusable element within the container, or, if provided, the element indicated by the `initialFocus` parameter (see API below).\n- External focus changes: If an external cause (e.g. mouse click, scripts, or accessibility software) results in an element outside the container to be focused, focus will immediately be redirected to the last-focused element that is inside the container.\n- Circular tab focus: Using the `TAB` key on the last focusable element within the container will result in the first focusable element within the container receiving focus. Similarly, `Shift+TAB` can be used to focus the last element from the first.\n- Global: Only one focus trap can be _active_ at a time. When a focus trap is enabled, if there is already an active focus trap, it becomes suspended and pushed onto a stack. Once the newly-active focus trap is disabled, the most recently-suspended trap will reactivate. Suspended focus traps can be disabled, causing them to be removed from the stack of suspended traps.\n\n### Demo\n\nTo see a demo, deploy Storybook and find the `useFocusTrap` stories.\n\n### Usage\n\n```ts\nfunction showDialog() {\n const dialog = document.getElementById('myDialog')\n if (dialog instanceof HTMLElement) {\n dialog.style.display = ''\n return focusTrap(dialog)\n }\n}\nfunction hideDialog(controller: AbortController) {\n document.getElementById('myDialog')?.style.display = 'none'\n controller.abort()\n}\nconst dialogController = showDialog()\n\n// later\nif (dialogController) {\n hideDialog(controller)\n}\n```\n\n### API\n\nThe `focusTrap` function takes the following arguments.\n\n| Name | Type | Default | Description |\n| :----------- | :------------- | :---------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| container | `HTMLElement` | | When active, only elements within this container (along with the container itself) can be focused. |\n| initialFocus | `HTMLElement` | | Specifies the element which will receive focus when the focus trap is activated. Defaults to the first tabbable element inside the container. |\n| signal | `AbortSignal?` | `undefined` | Optional abort signal to control the focus trap. If one is not provided, an `AbortController` will be returned, which can be used to disable the focus trap. |\n\n#### Return value\n\nIf the `signal` argument is omitted, `focusTrap()` will return an `AbortController`. This object has an `abort()` method, which can be called to disable the focus trap.\n\n### Best practices\n\n- Focus management is an important consideration for accessible applications. Sometimes poor focus management can make certain tasks impossible to complete for users not using a mouse. To learn more, read the [ARIA guidelines for keyboard focus](https://www.w3.org/TR/wai-aria-practices/#kbd_focus_discernable_predictable).\n- Only activate a focus trap if all UI outside of the trap container should be inert (non-interactive).\n- Avoid situations where multiple focus traps may be active (e.g. dialogs that open more dialogs). This behavior handles those situations, but the pattern may indicate poor UX.\n\n### A note on performance\n\nWhen focus trap is activated, it must perform [reflow](https://developers.google.com/speed/docs/insights/browser-reflow) to discover focusable elements. Use caution not to rapidly enable and disable focus traps.\n\n## useFocusTrap hook\n\nThe `useFocusTrap` hook is used to achieve focus trapping for React components. The hook returns a `ref` that must be applied to the focus trap container. The hook also returns a ref that can be used to indicate the initially-focused element when a focus trap is activated.\n\nThe focus trap can be disabled in two ways:\n\n1. Simply do not render the component. When a component that uses focus trapping is unmounted, its focus trap will be aborted automatically.\n2. Pass `disabled: true` to the settings argument of `useFocusTrap`.\n\nThe `useFocusTrap` hook also has an additional setting, `restoreFocusOnCleanUp`. If this is set to true, when the hook is either disabled (called with `disabled: true` or unmounted), we will attempt to re-focus the element that was focused immediately before the focus trap was enabled.\n\n### Using your own refs\n\nIf you would like to use your own refs, you can pass them into the hook as part of the settings object (see the interface below).\n\n### Usage\n\n```jsx\nexport const FocusTrapExample = () => {\n const {containerRef} = useFocusTrap()\n return (\n }>\n Apple \n Banana \n Cantaloupe \n
\n )\n}\n```\n\n### FocusTrapHookSettings interface\n\n`FocusTrapHookSettings` has the following properties:\n\n| Name | Type | Default | Description |\n| :-------------------- | :---------------- | :---------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| containerRef | `React.RefObject` | `undefined` | If provided, this will be the ref used to access the focus trap container. Otherwise, this hook will create the ref for you and return it. In both cases, the ref must be provided to the container element's JSX. |\n| initialFocusRef | `React.RefObject` | `undefined` | If provided, this will be the ref used to access the element that should receive initial focus when the focus trap is activated. Otherwise, this hook will create the ref for you and return it. If unused, the first tabbable element inside the container will be focused. |\n| disabled | `boolean` | `false` | If true, the previously-established focus trap for this container will be aborted. |\n| restoreFocusOnCleanUp | `boolean` | `false` | If true, attempt to restore focus to the previously-focused element when the trap is disabled or unmounted. |\n","parent":{"relativeDirectory":"","name":"focusTrap"}},{"fileAbsolutePath":"/home/runner/work/react/react/docs/content/focusZone.mdx","frontmatter":{"title":"Focus Zone Behavior"},"rawBody":"---\ntitle: Focus Zone Behavior\n---\n\nThe `focusZone` behavior and `useFocusZone` hook are used to designate a container where focus can be moved using keys other than `Tab`. This is useful for implementing many of the patterns described in [Section 6](https://www.w3.org/TR/wai-aria-practices-1.1/#keyboard) of the WAI-ARIA Authoring Practices document. The most common use case of this behavior is to allow arrow keys (up and down or left and right) to move focus between related elements, such as items in a menu.\n\nAt a high level, the `focusZone` behavior works by adjusting the `tabindex` attribute on focusable elements and setting up event listeners on the container that respond to the relevant key presses.\n\nSettings for this behavior allow the user to customize several aspects of the focus zone. See **FocusZoneSettings** below for a detailed description of these settings.\n\n### Focusability: which elements participate in the Focus Zone?\n\nWhen the `focusZone` behavior is established, it will discover all _focusable_ elements within the given container and allow them to be focused with the bound keys. _Focusable_ elements are those that either are normally focusable via the Tab key OR have a valid `tabindex` attribute (including `\"-1\"`). The easiest way to ensure an element participates in the focus zone is by applying the attribute `tabindex=\"-1\"`. If you need to prevent a focusable element from participating in the focus zone, you can provide a `focusableElementFilter`.\n\n### Focus order\n\nThe `focusZone` behavior uses the natural DOM ordering of elements to determine focus order. This means that a key that moves focus will either move to a \"next\" element or to a \"previous\" element. For example, the left arrow key and the up arrow key would both move focus to the previous element in the DOM order, while the right arrow key and the down arrow key would both move focus to the next element in the DOM order.\n\nFocus cannot be moved beyond the last element of the container (other than using the Tab key). The `focusOutBehavior` option can be used to allow focus to wrap around from last to first element (or vice-versa).\n\nFor a more customized focus movement behavior, the consumer has the ability to supply a custom callback that identifies the next element to focus.\n\n#### Entering the focus zone\n\nBy default, when focus enters a focus zone, the element that receives focus will be the most recently-focused element within that focus zone. If no element had previously been focused, or if that previously-focused element was removed, focus will revert to the first focusable element within the focus zone, regardless of the direction of focus movement.\n\nUsing the `focusInStrategy` option, you can change this behavior. Setting this option to `\"first\"` will simply cause the first focusable element in the container to be focused whenever focus enters the focus zone. Setting it to `\"closest\"` will cause either the first or last focusable element in the container to be focused depending on the direction of focus movement (for example, a shift+tab that brings focus to the container will cause the last focusable element to be focused, whereas a regular tab would cause the first focusable element to be focused). Otherwise, you may provide a callback to choose a custom element to receive initial focus. One scenario where this would be useful is if you wanted to focus an item that is \"selected\" in a list.\n\nFor more information on choosing the right focus in behavior, see [6.6 Keyboard Navigation Inside Components](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_general_within) from the ARIA Authoring Practices document.\n\n### Supported keys\n\nThe `focusZone` behavior supports different sets of keys for moving focus around. The `bindKeys` option is used to set which of the following keys can be used to move focus.\n\n| Key(s) | Notes | Use case |\n| :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |\n| ArrowVertical | Prevents default behavior of scrolling where applicable | Most focus zones with vertically-positioned elements |\n| ArrowHorizontal | Prevents default behavior of scrolling where applicable | Most focus zones with horizontally-positioned elements |\n| HomeAndEnd | Causes focus to jump to the first or last focusable item in the container. Does not move focus if the currently-focused element is a text box. | Generally used with arrow keys |\n| PageUpDown | Works the same as the Home and End keys. Advisable only when supplying a custom callback that supports paging. | In a long, scrollable list |\n| Tab/Shift+Tab | Unlike other keys, the Tab key will always allow movement outside of the focus zone (use the Focus Trap behavior to prevent this). Tab moves to the next item, Shift+Tab moves to the previous. | Bind Tab if you want to continue allowing tab to move focus between elements in your container rather than jumping out of the container. |\n| JK | J moves focus to the next item, K moves to the previous. Does not move focus if the currently-focused element is a text box. [Originally from](https://catonmat.net/why-vim-uses-hjkl-as-arrow-keys) the vi keybindings | Used in certain lists |\n| HL | H moves focus to the previous item, L moves to the next. Does not move focus if the currently-focused element is a text box. [Originally from](https://catonmat.net/why-vim-uses-hjkl-as-arrow-keys) the vi keybindings | Used in certain lists |\n| WS | W moves focus to the previous item, S moves to the next. Does not move focus if the currently-focused element is a text box. | Any situation where it is more ergonomic for the left hand to perform this action, such as in a gaming context (rare) |\n| AD | A moves focus to the previous item, D moves to the next. Does not move focus if the currently-focused element is a text box. | Any situation where it is more ergonomic for the left hand to perform this action, such as in a gaming context (rare) |\n\n### DOM Focus vs. Active Descendant\n\nThe `focusZone` behavior supports two modes of operation: DOM Focus and Active Descendant.\n\n- DOM Focus is the default mode and by far the most commonly needed. When a key is used to move focus, we call `.focus()` directly on the element to receive focus. This results in `document.activeElement` getting set to this new element, and it will receive any necessary styles via `:focus` and `:focus-within`.\n- Active Descendant mode does _not_ move DOM focus. Instead, focus remains on the _control_ element, and its `aria-activedescendant` attribute is set to the ID of the relevant element. Because there are no `:focus` styles applied and no `focus` events fired, you can supply an `onActiveDescendantChanged` callback to handle any necessary styles or other logic as the active descendant changes. For more information on the Active Descendant focus pattern, see [6.6.2 Managing Focus in Composites Using `aria-activedescendant`](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_focus_activedescendant) from the ARIA Authoring Practices document.\n\n### Demo\n\nDeploy Storybook to see live demos of `focusZone`.\n\n### Usage\n\n```ts\nconst settings = {\n bindKeys: FocusKeys.ArrowVertical | FocusKeys.HomeAndEnd\n} as FocusZoneSettings\nconst focusZone = document.getElementById('focusZoneContainer')\nfocusZone(focusZone, settings)\n```\n\n### API\n\nThe `focusZone` function takes the following arguments.\n\n| Name | Type | Default | Description |\n| :-------- | :------------------ | :-----: | :--------------------------------------------------------------------------------- |\n| container | `Element` | | The focus zone will apply to this container and all of its focusable descendants. |\n| settings | `FocusZoneSettings` | `{}` | Settings to customize the focus zone. See below for a description of each setting. |\n\n#### FocusZoneSettings interface\n\n`FocusZoneSettings` is an object with the following interface. All properties are optional and have default behaviors.\n\n| Name | Type | Default | Description |\n| :------------------------ | :-------------------------------------------- | :----------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| bindKeys | `FocusKeys` (numeric enum) | `FocusKeys.ArrowVertical │ FocusKeys.HomeAndEnd` | Bit flags that identify keys that will move focus around the focus zone. Each available key either moves focus to the \"next\", \"previous\", \"start\", or \"end\" element, so it is best to only bind the keys that make sense to move focus in your UI. Use the `FocusKeys` object to discover supported keys (listed in the \"Supported keys\" section above). \n First \n Second \n Third \n
\n )\n}\n```\n\n### useFocusZone hook\n\n| Name | Type | Default | Description |\n| :----------- | :---------------------- | :-------: | :------------------------------------------------------------------ |\n| settings | `FocusZoneHookSettings` | undefined | Optional settings to control how the focus zone behaves. See below. |\n| dependencies | `React.DependencyList` | undefined | Dependencies to determine when to initialize the focus zone. |\n\n**Return value**\n\n| Name | Type | Description |\n| :------------------------- | :----------------------------- | :---------------------------------------------------------------------------------------- |\n| containerRef | `React.RefObject` | This ref must be added to the container's JSX. |\n| activeDescendantControlRef | `React.RefObject` | If using active descendant focusing, this ref must be added to the control element's JSX. |\n\n### FocusZoneHookSettings interface\n\n`FocusZoneHookSettings` is an object with an interface that extends `FocusZoneSettings` (see above), however, the `activeDescendantControl` prop is omitted (instead see the `activeDescendantFocus` prop below). Additionally, it adds the following properties:\n\n| Name | Type | Default | Description |\n| :-------------------- | :--------------------------------------- | :---------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| containerRef | `React.RefObject` | `undefined` | If provided, this will be the ref used to access the element that will become the container of the focus zone. Otherwise, this hook will create the ref for you and return it. In both cases, the ref must be provided to the container's JSX. |\n| activeDescendantFocus | `boolean │ React.RefObject` | `false` | If false, the focus zone will apply normal DOM focusing (see **DOM Focus vs. Active Descendant** above). If true, or if a ref is provided, the focus zone will use \"active descendant\" focusing. If a ref is applied, it will be used as the control element for active descendant focus. If `true` is given, a ref will be created and returned by the hook. |\n| disabled | `boolean` | `false` | Set to true to disable the focus zone and clean up listeners. Can be re-enabled at any time. |\n","parent":{"relativeDirectory":"","name":"focusZone"}},{"fileAbsolutePath":"/home/runner/work/react/react/docs/content/getting-started.md","frontmatter":{"title":"Getting started"},"rawBody":"---\ntitle: Getting started\n---\n\n## Installation\n\nTo get started using Primer React, install the package and its peer dependencies with your package manager of choice:\n\n```bash\n# with npm\nnpm install @primer/react react react-dom styled-components\n\n# with yarn\nyarn add @primer/react react react-dom styled-components\n```\n\nYou can now import Primer React from the main package module:\n\n```javascript\n// using import syntax\nimport {Box} from '@primer/react'\n```\n\n```javascript\n// using require syntax\nconst {Box} = require('@primer/react')\n```\n\n### Polyfills & Browser Support\n\nPrimer React supports the current versions of [Chrome](https://www.google.com/chrome/), [Firefox](http://www.mozilla.org/firefox/), [Safari](http://www.apple.com/safari/), and [Microsoft Edge](https://www.microsoft.com/en-us/windows/microsoft-edge), as well as the [Firefox Extended Support Release](https://www.mozilla.org/en-US/firefox/organizations/). This is in-line with [GitHub's Browser Support](https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/supported-browsers).\n\nPrimer React does not transform code to support older ECMAScript versions, such as ES5, and it uses ECMAScript features such as `Object.assign`, as well as syntax features such as native classes and Object destructuring and spreading.\n\nEnvironments that Primer React is used in should have all the necessary polyfills to comply with the latest code standards, as Primer React will not ship with these. Additionally, as Primer React does not transform code to support older versions, it may be necessary for projects to transform this code if support for older browsers (such as Edge 18) is needed.\n\n### Minimizing bundle size\n\nModule bundlers that use ECMAScript modules (ESM) will automatically tree-shake Primer React, ensuring that no unused code is included in your final bundle. However, if you're not using ESM, you may be able to drastically reduce the size of your final bundle by importing components individually from the `lib` subfolder:\n\n```javascript\n// using import syntax\nimport Box from '@primer/react/lib/Box'\n```\n\n```javascript\n// using require syntax\nconst Box = require('@primer/react/lib/Box')\n```\n\nNote that the modules in the `lib` folder are CommonJS-style modules; if you're using ESM and a compatible module bundler, importing files individually from `lib` provides no benefit.\n\n### Peer dependencies\n\nPrimer React ships with a few libraries labeled as peer dependencies. These libraries are separated because they are commonly already installed in the host project and having multiple versions can introduce errors.\n\nPrimer React requires the following libraries to be installed along with it:\n\n- `styled-components` at version 4.0.0 or higher\n- `react` at versions 17.x or higher\n- `react-dom` at versions 17.x or higher\n\n## ThemeProvider\n\nFor Primer React to work correctly and accurately apply color schemes, you must add `ThemeProvider` to the root of your application:\n\n```jsx\nimport {ThemeProvider} from '@primer/react'\n\nfunction App() {\n return (\n \n ...
\n \n )\n}\n```\n\nSee [Theming](/theming) for more details on advanced configuration, color modes, and overriding theme values.\n\n## BaseStyles\n\nIn order to set baseline color, font-family, and line-heights across your project, you will need to establish base Primer styles for your app by wrapping all of your Primer components in `` at the root of your app:\n\n```jsx\nimport {BaseStyles, Box, Heading} from '@primer/react'\n\nexport default () => (\n \n \n Hello, world! \n This will get Primer text styles.
\n \n \n)\n```\n\nThis will apply the same `color`, `font-family`, and `line-height` styles to the `` as [Primer CSS's base styles](https://github.com/primer/css/blob/master/src/base/base.scss#L15-L20).\n\n## Static CSS rendering\n\nIf you're rendering React components both server- and client-side, we suggest following [styled-component's server-side rendering instructions](https://www.styled-components.com/docs/advanced#server-side-rendering) to avoid the flash of unstyled content for server-rendered components.\n\n## TypeScript\n\nPrimer React includes TypeScript support and ships with its own typings. You will still need to install type definitions for the peer dependencies if you import those in your own application code.\n\nOnce installed, you can import components and their prop type interfaces from the `@primer/react` package:\n\n```typescript\nimport {BorderBox, BorderBoxProps} from '@primer/react'\n```\n\n### Fixing \"Duplicate identifier 'FormData'\"\n\nEver since `@types/styled-components` version `4.1.19`, it has had a dependency on both `@types/react` and `@types/react-native`. Unfortunately, those declarations clash; for more information, see [issue 33311](https://github.com/DefinitelyTyped/DefinitelyTyped/issues/33311) and [issue 33015](https://github.com/DefinitelyTyped/DefinitelyTyped/issues/33015) in the DefinitelyTyped repo.\n\nYou may run into this conflict even if you're not importing anything from `react-native` or don't have it installed. This is because some package managers hoist packages to the top-level `node_modules` folder, and the TypeScript compiler automatically includes types from all folders in `node_modules/@types` by default.\n\nThe TypeScript compiler allows you to opt-out of this behavior [using the `typeRoots` and `types` configuration options](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html#types-typeroots-and-types), and the best solution for this error — for now — seems to be to opt out the automatic inclusion of `node_modules/@types` and instead list the types you want to be included individually.\n\nIn your `tsconfig.json`, set the `types` array under the `compilerOptions` like so:\n\n```json\n{\n \"compilerOptions\": {\n \"types\": [\"node\", \"react\", \"styled-components\", \"jest\"]\n }\n}\n```\n\nOf course, customize the array based on the `@types/` packages you have installed for your project.\n\n## Silencing warnings\n\nLike React, Primer React emits warnings to the JavaScript console under certain conditions, like using deprecated components or props. Similar to React, you can silence these warnings by setting the `NODE_ENV` environment variable to `production` during bundling.\n","parent":{"relativeDirectory":"","name":"getting-started"}},{"fileAbsolutePath":"/home/runner/work/react/react/docs/content/index.md","frontmatter":{"title":"Getting started"},"rawBody":"---\ntitle: Getting started\n---\n\nimport {HeroLayout} from '@primer/gatsby-theme-doctocat'\nexport default HeroLayout\n\n## Primer React\n\nPrimer React is a React implementation of GitHub's [Primer Design System](https://primer.style/) 🎉\n\n## Principles\n\n- Everything is a component.\n- Aim for total style encapsulation; don't rely on inheritance to provide default styles.\n- Build small building blocks with minimal props to keep complexity low.\n- Keep system constrained by only including props needed per component.\n- Favor wrapping or extending components for more complex operations.\n- Maintain design system consistency with utilities as props (for spacing, color, font-size, line-height, widths, and radii).\n\n## Getting started\n\nCheck out [our getting started guide](/getting-started) for everything you need to know about installing and using Primer React.\n\n## Local development\n\nTo run `@primer/react` locally when adding or updating components:\n\n1. Clone this repo: `git clone https://github.com/primer/react`\n2. Install dependencies: `npm install`\n3. Run the dev app: `npm start`\n\n> 👉 See [the contributing docs](https://github.com/primer/react/blob/main/contributor-docs/CONTRIBUTING.md) for more info on code style, testing, and coverage.\n","parent":{"relativeDirectory":"","name":"index"}},{"fileAbsolutePath":"/home/runner/work/react/react/docs/content/linting.md","frontmatter":{"title":"Linting"},"rawBody":"---\ntitle: Linting\ndescription: Primer React offers an ESLint plugin to enforce best practices and fix common problems. \n---\n\n\n\n`eslint-plugin-primer-react` is experimental. Please report issues in the [primer/react](https://github.com/primer/react) repository.\n\n \n\n## Installation\n\n1. Assuming you already have [ESLint](https://www.npmjs.com/package/eslint) and [Primer React](https://github.com/primer/react) installed, run:\n\n ```shell\n npm install --save-dev eslint-plugin-primer-react\n\n # or\n \n yarn add --dev eslint-plugin-primer-react\n ```\n\n2. In your [ESLint configuration file](https://eslint.org/docs/user-guide/configuring/configuration-files), extend the recommended Primer React ESLint config:\n\n ```json\n {\n \"extends\": [\n // ...\n \"plugin:primer-react/recommended\"\n ]\n }\n ```\n\nSee the [eslint-plugin-primer-react](https://github.com/primer/eslint-plugin-primer-react) repository for a list of included lint rules.\n","parent":{"relativeDirectory":"","name":"linting"}},{"fileAbsolutePath":"/home/runner/work/react/react/docs/content/overriding-styles.mdx","frontmatter":{"title":"Overriding styles with the sx prop"},"rawBody":"---\ntitle: Overriding styles with the sx prop\n---\n\nOur goal with Primer React is to hit the sweet spot between providing too little and too much styling flexibility; too little and the design system is too rigid, and too much and it becomes too difficult to maintain a consistent style. Our components are designed to cover common usage patterns, but sometimes a component just isn't _quite_ flexible enough to look the way you need it to look. For those cases, we provide the `sx` prop.\n\nThe `sx` prop allows ad-hoc styling that is still theme-aware. Declare the styles you want to apply in CamelCase object notation, and try to use theme values in appropriate CSS properties when possible. If you've passed a custom theme using `ThemeProvider` or a `theme` prop, the `sx` prop will honor the custom theme. For more information on theming in Primer React, check out [the Primer Theme documentation](/primer-theme).\n\n## When to use the `sx` prop\n\nThe `sx` prop provides a lot of power, which means it is an easy tool to abuse. To best make use of it, we recommend following these guidelines:\n\n- Use the `sx` prop for small stylistic changes to components. For more substantial changes, consider abstracting your style changes into your own wrapper component.\n- Avoid nesting and pseudo-selectors in `sx` prop values when possible.\n\n## Basic example\n\nThis example demonstrates applying a bottom border to `Heading`, a component that does not receive `BORDER` system props. The `borderBottomWidth` value comes from `theme.borderWidths` and `borderBottomColor` comes from `theme.colors`.\n\n```jsx live\n<>\n Heading \n\n \n Heading with bottom border\n \n\n```\n\n## Responsive values\n\nJust like [values passed to system props](https://styled-system.com/responsive-styles), values in the `sx` prop can be provided as arrays to provide responsive styling.\n\n```jsx live\n\n Responsive background color\n\n```\n\n## Nesting, pseudo-classes, and pseudo-elements\n\nThe `sx` prop also allows for declaring styles based on media queries, pseudo-classes, and pseudo-elements. This example, though contrived, demonstrates the ability:\n\n```jsx live\n *': {\n borderWidth: 1,\n borderColor: 'border.default',\n borderStyle: 'solid',\n borderBottomWidth: 0,\n padding: 2,\n ':last-child': {\n borderBottomWidth: 1\n },\n ':hover': {\n bg: 'neutral.muted'\n }\n }\n }}\n>\n First \n Second \n Third \n\n```\n","parent":{"relativeDirectory":"","name":"overriding-styles"}},{"fileAbsolutePath":"/home/runner/work/react/react/docs/content/philosophy.md","frontmatter":{"title":"Primer React Philosophy"},"rawBody":"---\ntitle: Primer React Philosophy\n---\n\n## Presentational Components\n\nWe are focusing primarily on presentational components that help standardize common design patterns. Primer React components don't handle fetching and submitting data to/from APIs. If you would like to handle data in a Primer Component, feel free to create a wrapper around the Primer Component to do so.\n\n## Assume that people will break the rules, provide safe ways for them to do so\n\nWhile we aim to standardize design in Primer React, we also provide additional styling flexibility through the [`sx` prop](/overriding-styles). This enables small customizations to color and spacing, using values from the theme. Users also have the option to override the theme with a theme of their own.\n\n## Pattern Components vs Helper Components\n\nOur components can roughly be categorized into two different component types:\n\n- Pattern Components\n\nPattern components help us repeat commonly used UI patterns and interactions in order to maintain our brand and provide a great user experience. Some examples of pattern components are `Button`, `Avatar`, or `Label`.\n\n- Helper Components\n\nHelper components are components that help the user achieve common CSS patterns while maintaining some control over values used. An example of a helper component is `Box`.\n","parent":{"relativeDirectory":"","name":"philosophy"}},{"fileAbsolutePath":"/home/runner/work/react/react/docs/content/primer-theme.md","frontmatter":{"title":"Primer Theme"},"rawBody":"---\ntitle: Primer Theme\n---\n\nimport {theme} from '@primer/react'\n\nPrimer React components come with built-in access to our Primer theme. The [theme file](https://github.com/primer/react/blob/main/src/theme-preval.ts) contains an object which holds values for common variables such as color, fonts, box shadows, and more. Our theme file pulls many of its color and typography values from [primer-primitives](https://github.com/primer/primer-primitives).\n\nMany of our theme keys correspond to system props on our components. For example, if you'd like to set the max width on a `` set the `maxWidth` prop to `medium`: ``\n\nIn the background, [styled-system](https://github.com/styled-system/styled-system) does the work of finding the `medium` value from `maxWidth` key in the theme file and applying the corresponding CSS.\n\nOur full theme can be found [here](https://github.com/primer/react/blob/main/src/theme-preval.js).\n\n### Custom Theming\n\nCustom theming is an optional way to override the Primer values that control color, spacing, typography, and other aspects of our components.\n\nThere are two ways to change the theme of Primer components:\n\n1. You can override the entire theme for an entire tree of components using the `` from [styled-components]:\n\n ```javascript\n import {Box, Button, Text, theme as primer} from '@primer/react'\n import {ThemeProvider} from 'styled-components'\n\n // a theme with custom spacing and font sizes\n const theme = {\n ...primer,\n space: [0, 8, 16, 32, 64],\n fontSizes: [10, 12, 16, 24, 48]\n }\n\n // override\n theme.colors.bodytext = '#111'\n\n export default () => (\n \n \n Hello, world! \n \n \n )\n ```\n\n **⚠️ Note: [styled-components]'s `` only allows exactly one child.**\n\n2. You can merge the Primer theme with your custom theme using Object.assign:\n\n ```javascript\n import {ThemeProvider} from `styled-components`\n import {theme} from '@primer/react'\n\n const customTheme = {} // Theme overrides\n\n const App = (props) => {\n return (\n \n
// matching keys in customTheme will override keys in the Primer theme\n your app here
\n \n
\n Hi, I'm magenta!\n \n )\n ```\n\n **☝️ This is an intentionally convoluted example, since you can use `` out of the box.**\n\nRead the [styled-system docs](https://styled-system.com/#theming) for more information on theming in styled-system.\n\n[styled-components]: https://styled-components.com/\n","parent":{"relativeDirectory":"","name":"primer-theme"}},{"fileAbsolutePath":"/home/runner/work/react/react/docs/content/ssr.mdx","frontmatter":{"title":"Server-side rendering with Primer React"},"rawBody":"---\ntitle: Server-side rendering with Primer React\n---\n\n## SSR-safe ID generation\n\nSome Primer components generate their own DOM IDs. Those IDs must be isomorphic (so that server-side rendering and client-side rendering yield the same ID, avoiding hydration issues) and unique across the DOM. We use [@react-aria/ssr](https://react-spectrum.adobe.com/react-aria/ssr.html) to generate those IDs. In client-only rendering, this doesn't require any additional work. In SSR contexts, you must wrap your application with at least one `SSRProvider`:\n\n```\nimport {SSRProvider} from '@primer/react';\n\nfunction App() {\n return (\n \n \n )\n}\n```\n\n`SSRProvider` maintains the context necessary to ensure IDs are consistent. In cases where some parts of the react tree are rendered asynchronously, you should wrap an additional `SSRProvider` around the conditionally rendered elements:\n\n```\nfunction MyApplication() {\n const [dataA] = useAsyncData('a');\n const [dataB] = useAsyncData('b');\n\n return (\n <>\n \n {dataA && \n \n {dataB && \n \n )\n}\n```\n\nThis will ensure that the IDs are consistent for any sequencing of `dataA` and `dataB` being resolved.\n\nSee also [React Aria's server side rendering documentation](https://react-spectrum.adobe.com/react-aria/ssr.html).\n","parent":{"relativeDirectory":"","name":"ssr"}},{"fileAbsolutePath":"/home/runner/work/react/react/docs/content/status.mdx","frontmatter":{"title":"Component status"},"rawBody":"---\ntitle: Component status\ndescription: Check the current status of Primer React components\n---\n\nimport {ComponentStatuses} from '../src/component-statuses'\n\nSee the [component lifecycle](https://primer.style/contribute/component-lifecycle) for more information about each status.\n\n\n\nSystem props are deprecated in all components except [Box](/Box) and [Text](/Text). Please use the [`sx` prop](/overriding-styles) instead.\n\n \n\nPrimer React components utilize what we call \"system props\" to apply a standard set of props to each component. Using [styled-system](https://github.com/jxnblk/styled-system), groups of props are automatically applied to each component. Most components get the `COMMON` set of props which give the component access to color and space props (margin, padding, color and background color). These groups correspond to the `color` and `space` functions from `styled-system` which can be referenced in the styled system [table of style functions](https://github.com/jxnblk/styled-system/blob/master/docs/table.md#core).\n\nTo check which system props each component includes, check the documentation for that component.\n\n### The `as` prop\n\nAll Primer React components have access to the `as` prop, provided by [styled-components](https://www.styled-components.com/docs/api#as-polymorphic-prop). We use the `as` prop to render a component with the styles of the passed component in `as`, but with the system props of the base component.\n\nFor example, if you wanted to add some flex utilities to the `Text` component, you could do:\n\n```jsx live deprecated\nHello! \n```\n\n### System Prop Categories\n\n| Category | Included Props | styled-system docs |\n| ------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `COMMON` | | [styled-system core docs](https://github.com/jxnblk/styled-system/blob/master/docs/table.md#core) |\n| `TYPOGRAPHY` | | [styled-system typography docs](https://github.com/jxnblk/styled-system/blob/master/docs/table.md#typography) |\n| `BORDER` | | [styled-system border docs](https://github.com/jxnblk/styled-system/blob/master/docs/table.md#border) |\n| `LAYOUT` | | [styled-system layout docs](https://github.com/jxnblk/styled-system/blob/master/docs/table.md#layout) \n\nSee [Theming](/theming) to learn how theming works in Primer React.\n\n \n\nColors in this theme object are imported from [Primer Primitives](https://primer.style/primitives/colors).\n\n{JSON.stringify(theme, null, 2)}\n ...
\n \n )\n}\n```\n\n`ThemeProvider` comes with a [default theme object](/theme-reference) that includes colors, spacing, fonts, etc. for building applications at GitHub.\n\n## Customizing the theme\n\nTo customize the [default theme](/theme-reference), you can pass your custom theme to `ThemeProvider` using the `theme` prop:\n\n```jsx\nimport {ThemeProvider, theme} from '@primer/react'\nimport deepmerge from 'deepmerge'\n\nconst customTheme = deepmerge(theme, {\n fonts: {\n mono: 'MonoLisa, monospace'\n }\n})\n\nfunction App() {\n return (\n \n ...
\n \n )\n}\n```\n\nSome components may break if your custom theme does not include all the same keys as the [default theme](/theme-reference). For that reason, we recommend extending the default theme using [deepmerge](https://www.npmjs.com/package/deepmerge).\n\n## Referencing theme values\n\nYou can reference theme values in your application using the [`sx` prop](/overriding-styles), the `themeGet` function, or the `useTheme` hook.\n\n\n\nOnly use `theme` objects accessed via Primer's theme context to ensure your application’s styling draws from the same theme as Primer components’ internal styling. The `sx` prop, styled system props, `themeGet`, and `useTheme` all use the theme from context.\n\n\n \n \n {``}\n \n Use the theme from the same context as Primer. \n \n \n \n {`import {theme} from '@primer/react'\\n\\n`}\n \n Don't style components with any other instance of theme \n \n \n\n \n\n### System props and the `sx` prop\n\nSome [system props](/system-props) and [`sx` prop](/overriding-styles) keys are theme-aware. For example, the `bg` prop maps to the `colors` theme key which means you can use the `bg` prop to reference values in the `colors` object:\n\n```jsx\nconst theme = {\n colors: {\n canvas: {\n default: '#fff'\n }\n }\n}\n\nfunction App() {\n return (\n \n \n )\n}\n```\n\nSee the [Styled System Reference Table](https://styled-system.com/table) for a complete list of mappings.\n\n### themeGet\n\nThe `themeGet` function is a convenient way to reference theme values in styled-components template literals:\n\n```js\nimport {themeGet} from '@primer/react'\nimport styled from 'styled-components'\n\nconst Example = styled.div`\n background-color: ${themeGet('colors.canvas.default')};\n`\n```\n\n### useTheme\n\nYou can use the `useTheme` hook to reference theme values from inside any function component nested under the `ThemeProvider`:\n\n```js\nimport {ThemeProvider, useTheme} from '@primer/react'\n\nfunction Example() {\n const {theme} = useTheme()\n // theme.colors.canvas.default\n}\n\nfunction App() {\n return (\n \n \n )\n}\n```\n\n\n\nOnly use `useTheme` to reference theme values in places where it's not possible to use system props, the `sx` prop, or `themeGet`.\n\n \n\n## Color modes and color schemes\n\nThe terms \"color mode\" and \"color scheme\" are often used interchangeably. However, in Primer React, they are two separate (but related) concepts.\n\nThe \"color mode\" of an application can be either `day`, `night`, or `auto` (i.e. synced with the operating system).\n\nA \"color scheme\", on the other hand, is a collection of colors that can be associated with a color mode. The [default theme](/theme-reference) includes three color schemes: `light`, `dark`, and `dark_dimmed`. By default, the `light` scheme is displayed when the application is in `day` mode and the `dark` scheme is displayed in `night` mode.\n\n### Setting the color mode\n\nBy default, Primer React is in `day` mode. To change the color mode, use the `colorMode` prop on `ThemeProvider` or the `setColorMode` function from the `useTheme` hook:\n\n#### `colorMode` prop\n\n```jsx\nimport {ThemeProvider} from '@primer/react'\n\nfunction App() {\n return (\n // colorMode can be \"day\" (default), \"night\", or \"auto\"\n \n ...
\n \n )\n}\n```\n\n#### `setColorMode` function\n\n```jsx\nimport {useTheme} from '@primer/react'\n\nfunction Example() {\n const {setColorMode} = useTheme()\n return setColorMode('auto')}>Activate auto mode \n}\n```\n\n#### `preventSSRMismatch` prop\n\nIf you are doing server-side rendering, pass the `preventSSRMismatch` prop to ensure the rendered output from the server and browser match even when they resolve \"auto\" color mode differently.\n\n```jsx\n\n ...\n \n```\n\n### Setting color schemes\n\nTo choose which color schemes will be displayed in `day` and `night` mode, use the `dayScheme` and `nightScheme` props on `ThemeProvider` or the `setDayScheme` and `setNightScheme` functions from the `useTheme` hook:\n\n#### `dayScheme` and `nightScheme` props\n\n```jsx\nimport {ThemeProvider} from '@primer/react'\n\nfunction App() {\n return (\n // The default theme includes `light`, `dark`, and `dark_dimmed` schemes\n \n ...
\n \n )\n}\n```\n\n#### `setDayScheme` and `setNightScheme` functions\n\n```jsx\nimport {useTheme} from '@primer/react'\n\nfunction Example() {\n const {setDayScheme, setNightScheme} = useTheme()\n return setNightScheme('auto')}>Activate auto mode \n}\n```\n\n### Customizing or adding color schemes\n\nTo customize or add color schemes, update the `colorSchemes` object in the theme:\n\n```jsx\nimport {ThemeProvider, theme} from '@primer/react'\nimport deepmerge from 'deepmerge'\n\nconst customTheme = deepmerge(theme, {\n colorSchemes: {\n // Customize an existing scheme\n light: {\n colors: {\n text: {\n primary: '#f00'\n }\n }\n },\n // Add a new scheme\n my_scheme_name: {\n colors: {},\n shadows: {}\n }\n }\n})\n\nfunction App() {\n return (\n \n ...
\n \n )\n}\n```\n\n### Creating local color scheme variables\n\nIf you need to use a color that is not defined in the theme, avoid hard coding the color value like this:\n\n```jsx\nfunction Example() {\n return (\n // BAD: #aaa may not look good in all color schemes\n Hello world \n )\n}\n```\n\nInstead, use the `useColorSchemeVar` hook to create a local variable that will update based on the active color scheme:\n\n```jsx\nimport {useColorSchemeVar} from '@primer/react'\nimport {colors} from '@primer/primitives'\n\nfunction Example() {\n // GOOD: The value of `customBg` changes based on the active color scheme\n const customBg = useColorSchemeVar({\n light: colors.light.scale.gray[1],\n dark: colors.dark.scale.gray[9],\n dark_dimmed: colors.dark_dimmed.scale.gray[2]\n })\n return Hello world \n}\n```\n","parent":{"relativeDirectory":"","name":"theming"}},{"fileAbsolutePath":"/home/runner/work/react/react/docs/content/useOnEscapePress.mdx","frontmatter":{"title":"useOnEscapePress"},"rawBody":"---\ntitle: useOnEscapePress\n---\n\n`useOnEscapePress` is a simple utility Hook that calls a user-provided function when the `Escape` key is pressed. The hook sets up `keydown` event listener on `window.document` and executes the user-provided function if these conditions are met:\n\n1. The Escape key was pressed\n2. The `preventDefault` method has not yet been called on the event object.\n\nFurthermore, unlike the normal behavior for multiple event listeners existing on the same DOM Node, if multiple `useOnEscapePress` hooks are active simultaneously, the callbacks will occur in reverse order. In other words, if a parent component and a child component both call `useOnEscapePress`, when the user presses Escape, the child component's callback will execute, followed by the parent's callback. Each callback has the chance to call `.preventDefault()` on the event to prevent further callbacks.\n\n### Dependencies\n\nSimilar to `useCallback`, `useOnEscapePress` takes a `React.DependencyList` as its second argument. These are the dependencies used to memoize the callback. Failing to provide the correct dependency list can result in degraded performance. If this argument is omitted, we will assume that the callback is already memoized. In the example below, that memoization occurs in `DemoComponent` with a call to `React.useCallback`, so `OverlayDemo` does not need to pass a dependency list.\n\n### Usage\n\n```javascript live noinline\nconst OverlayDemo = ({onEscape, children}) => {\n useOnEscapePress(onEscape)\n return (\n \n {children}\n \n )\n}\n\nfunction DemoComponent() {\n const [isOpen, setIsOpen] = React.useState(false)\n const toggleOverlay = React.useCallback(() => {\n setIsOpen(isOpen => !isOpen)\n }, [])\n const closeOverlay = React.useCallback(() => {\n setIsOpen(false)\n }, [])\n return (\n <>\n toggle \n {isOpen &&\n \n Button One \n Button Two \n }\n \n )\n}\n\nrender(\n {([isOpen, setIsOpen]) => {\n const containerRef = React.useRef(null)\n const triggerRef = React.useRef(null)\n\n const closeOverlay = React.useCallback(() => {\n setIsOpen(false)\n }, [setIsOpen])\n\n const toggleOverlay = React.useCallback(() => {\n setIsOpen(!isOpen)\n }, [setIsOpen, isOpen])\n\n useOnOutsideClick({onClickOutside: closeOverlay, containerRef, ignoreClickRefs: [triggerRef]})\n\n return (\n <>\n \n toggle\n \n {isOpen && (\n \n content\n \n )}\n \n )\n }}\n\n```\n\n#### useOnOutsideClick settings\n\n| Name | Type | Default | Description |\n| :------------- | :-------------------------------- | :-----: | :------------------------------------------------------------------------------------------------------------------------------ |\n| onOutsideClick | `function` | | Function to call when user clicks outside of the container. Usually this manages the state of the visibility of the container. |\n| ignoredRefs | `React.RefObject []` | | Elements outside of the container to ignore clicks on. |\n| containerRef | `React.RefObject` | | Required. A ref for the containing element. |\n","parent":{"relativeDirectory":"","name":"useOnOutsideClick"}},{"fileAbsolutePath":"/home/runner/work/react/react/docs/content/useOpenAndCloseFocus.mdx","frontmatter":{"title":"useOpenAndCloseFocus"},"rawBody":"---\ntitle: useOpenAndCloseFocus\n---\n\n`useOpenAndCloseFocus` is a utility Hook that manages focusing an element when a component is first mounted, and returns focus to an element on the page when that component unmounts.\n\nIf no ref is passed to `initialFocusRef` , the hook focuses the first focusable element inside of the container.\n\n\n### Usage\n\n```javascript live noinline\nconst Overlay = ({returnFocusRef, initialFocusRef, children}) => {\n const containerRef = React.useRef(null)\n useOpenAndCloseFocus({containerRef, returnFocusRef, initialFocusRef})\n return (\n \n {children}\n \n )\n}\n\nfunction Component() {\n const returnFocusRef = React.useRef(null)\n const initialFocusRef = React.useRef(null)\n const [isOpen, setIsOpen] = React.useState(false)\n return (\n \n setIsOpen(!isOpen)}>toggle \n {isOpen &&\n \n Button One \n Button Two \n }\n \n )\n}\n\nrender(` | | Optional. The element to focus when the container is mounted on the page. |\n| returnFocusRef | `React.RefObject` | | Required. The element to focus when the container is unmounted. |\n| containerRef | `React.RefObject` | | Required. A ref for the containing element. |\n","parent":{"relativeDirectory":"","name":"useOpenAndCloseFocus"}},{"fileAbsolutePath":"/home/runner/work/react/react/docs/content/useOverlay.mdx","frontmatter":{"title":"useOverlay"},"rawBody":"---\ntitle: useOverlay\n---\n\n`useOverlay` calls all of the relevant behavior Hooks that all `Overlay` components & composite components should have and returns a ref to be passed down to the overlay's container.\n\nThese behaviors include:\n\n- Correctly positioning the component based on the values provided to `positionSettings` and `positionDeps`.\n- Trapping focus\n- Calling a user provided function when the user presses `Escape`\n- Calling a user provided function when the user clicks outside of the container\n- Focusing the either a user provided element, or the first focusable element in the container when it is opened.\n- Returning focus to an element when container is closed\n\n**Note:** `useOverlay` and `Overlay` do not manage the open state of the overlay. We leave control of the open state up to the user. All behaviors are built with the assumption that the overlay will not be rendered on the page & fully unmounted when it is not visible. See the examples for details on how to conditionally render a component in JSX.\n\n### Usage\n\n```javascript live noinline\n\nconst DemoOverlay = ({onClickOutside, initialFocusRef, returnFocusRef, ignoreClickRefs, onEscape, ...rest}) => {\n const overlayProps = useOverlay({returnFocusRef, onEscape, ignoreClickRefs, onClickOutside, initialFocusRef})\n return setIsOpen(!isOpen)}>toggle \n {isOpen &&\n \n Button One \n Button Two \n }\n \n )\n}\n\nrender( []` | optional | Refs to click clicks on in the `onOutsideClick` function, useful for ignoring clicks on elements that trigger the overlay visibility. |\n| initialFocusRef | `React.RefObject` | optional | Ref to focus when overlay is mounted. |\n| returnFocusRef | `React.RefObject` | required | Ref to focus when overlay is unmounted. Important for accessibility. |","parent":{"relativeDirectory":"","name":"useOverlay"}},{"fileAbsolutePath":"/home/runner/work/react/react/docs/content/useSafeTimeout.mdx","frontmatter":{"title":"useSafeTimeout"},"rawBody":"---\ntitle: useSafeTimeout\n---\n\n`useSafeTimeout` is a utility Hook that allows you to safely call `setTimeout` and `clearTimeout` within a component, ensuring that all timeouts are cleared when the component unmounts.\n\n\n### Usage\n\n```jsx live\n\n {([]) => {\n const {safeSetTimeout, safeClearTimeout} = useSafeTimeout()\n let timeoutId = null\n\n const handleOnClick = () => {\n timeoutId = safeSetTimeout(() => window.alert('hello!'), 5000)\n }\n\n const cancelTimeout = () => {\n safeClearTimeout(timeoutId)\n }\n\n return (\n <>\n Click me \n Cancel timeout \n \n )\n }}\n \n```\n","parent":{"relativeDirectory":"","name":"useSafeTimeout"}},{"fileAbsolutePath":"/home/runner/work/react/react/docs/content/deprecated/ActionList.mdx","frontmatter":{"title":"ActionList (legacy)"},"rawBody":"---\ntitle: ActionList (legacy)\nstatus: Deprecated\nsource: https://github.com/primer/react/tree/main/src/deprecated/ActionList\n---\n\nAn `ActionList` is a list of items which can be activated or selected. `ActionList` is the base component for many of our menu-type components, including `DropdownMenu` and `ActionMenu`.\n\n## Deprecation\n\nUse [new version of ActionList](/ActionList) with composable API, design updates and accessibility fixes.\n\n**Before**\n\n```jsx\n\n New file \n Copy link \n Edit file \n Delete file \n \n```\n\nOr continue using deprecated API:\n\n```js\nimport {ActionList} from '@primer/react/deprecated'\n```\n\n## Minimal example\n\n```jsx live deprecated\n \n \n )\n }\n ]}\n/>\n```\n\n## Props\n\n| Name | Type | Default | Description |\n| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| items | `(ItemProps & Omit, keyof ItemProps>) \\| ((Partial & {renderItem: RenderItemFn}) & {key?: Key})` | `undefined` | Required. A list of item objects conforming to the `ActionList.Item` props interface. |\n| renderItem | `(props: ItemProps) => JSX.Element` | `ActionList.Item` | Optional. If defined, each item in `items` will be passed to this function, allowing for `ActionList`-wide custom item rendering. |\n| groupMetadata | `GroupProps[]` | `undefined` | Optional. If defined, `ActionList` will group `items` into `ActionList.Group`s separated by `ActionList.Divider` according to their `groupId` property. |\n| showItemDividers | `boolean` | `false` | Optional. If `true` dividers will be displayed above each `ActionList.Item` which does not follow an `ActionList.Header` or `ActionList.Divider` |\n","parent":{"relativeDirectory":"deprecated","name":"ActionList"}},{"fileAbsolutePath":"/home/runner/work/react/react/docs/content/deprecated/ActionMenu.mdx","frontmatter":{"title":"ActionMenu (legacy)"},"rawBody":"---\ntitle: ActionMenu (legacy)\nstatus: Deprecated\nsource: https://github.com/primer/react/tree/main/src/deprecated/ActionMenu.tsx\n---\n\nAn `ActionMenu` is an ActionList-based component for creating a menu of actions that expands through a trigger button.\n\n## Deprecation\n\nUse [new version of ActionMenu](/ActionMenu) with composable API, design updates and accessibility fixes.\n\n**Before**\n\n```jsx\n\n Menu \n \n \n New file \n Copy link \n Edit file \n Delete file \n \n \n \n```\n\nOr continue using deprecated API:\n\n```js\nimport {ActionMenu} from '@primer/react/deprecated'\n```\n\n## Default example\n\n```jsx live deprecated\n console.log(text)}\n items={[\n {text: 'New file', key: 'new-file'},\n ActionMenu.Divider,\n {text: 'Copy link', key: 'copy-link'},\n {text: 'Edit file', key: 'edit-file'},\n {text: 'Delete file', variant: 'danger', key: 'delete-file'}\n ]}\n/>\n```\n\n## Example with grouped items\n\n```jsx live deprecated\n console.log(text)}\n groupMetadata={[\n {groupId: '0'},\n {groupId: '1', header: {title: 'Live query', variant: 'subtle'}},\n {groupId: '2', header: {title: 'Layout', variant: 'subtle'}},\n {groupId: '3'},\n {groupId: '4'}\n ]}\n items={[\n {key: '1', leadingVisual: TypographyIcon, text: 'Rename', groupId: '0'},\n {key: '2', leadingVisual: VersionsIcon, text: 'Duplicate', groupId: '0'},\n {key: '3', leadingVisual: SearchIcon, text: 'repo:github/github', groupId: '1'},\n {\n key: '4',\n leadingVisual: NoteIcon,\n text: 'Table',\n description: 'Information-dense table optimized for operations across teams',\n descriptionVariant: 'block',\n groupId: '2'\n },\n {\n key: '5',\n leadingVisual: ProjectIcon,\n text: 'Board',\n description: 'Kanban-style board focused on visual states',\n descriptionVariant: 'block',\n groupId: '2'\n },\n {\n key: '6',\n leadingVisual: FilterIcon,\n text: 'Save sort and filters to current view',\n disabled: true,\n groupId: '3'\n },\n {key: '7', leadingVisual: FilterIcon, text: 'Save sort and filters to new view', groupId: '3'},\n {key: '8', leadingVisual: GearIcon, text: 'View settings', groupId: '4'}\n ]}\n/>\n```\n\n## Component props\n\n| Name | Type | Default | Description |\n| :------------ | :------------------------------------ | :---------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| items | `ItemProps[]` | `undefined` | Required. A list of item objects conforming to the `ActionList.Item` props interface. |\n| renderItem | `(props: ItemProps) => JSX.Element` | `ActionList.Item` | Optional. If defined, each item in `items` will be passed to this function, allowing for `ActionList`-wide custom item rendering. |\n| groupMetadata | `GroupProps[]` | `undefined` | Optional. If defined, `ActionList` will group `items` into `ActionList.Group`s separated by `ActionList.Divider` according to their `groupId` property. |\n| renderAnchor | `(props: ButtonProps) => JSX.Element` | `Button` | Optional. If defined, provided component will be used to render the menu anchor. Will receive the selected `Item` text as `children` prop when an item is activated. |\n| anchorContent | React.ReactNode | `undefined` | Optional. If defined, it will be passed to the trigger as the elements child. |\n| onAction | (props: ItemProps) => void | `undefined` | Optional. If defined, this function will be called when a menu item is activated either by a click or a keyboard press. |\n| open | boolean | `undefined` | Optional. If defined, ActionMenu will use this to control the open/closed state of the Overlay instead of controlling the state internally. Should be used in conjunction with the `setOpen` prop. |\n| setOpen | (state: boolean) => void | `undefined` | Optional. If defined, ActionMenu will use this to control the open/closed state of the Overlay instead of controlling the state internally. Should be used in conjunction with the `open` prop. |\n","parent":{"relativeDirectory":"deprecated","name":"ActionMenu"}},{"fileAbsolutePath":"/home/runner/work/react/react/docs/content/deprecated/BorderBox.md","frontmatter":{"title":"BorderBox"},"rawBody":"---\ntitle: BorderBox\nstatus: Deprecated\n---\n\nBorderBox is a Box component with a border. When no `borderColor` is present, the component defaults to a primary border.\n\n## Deprecation\n\nUse [Box](/Box) instead.\n\n**Before**\n\n```jsx deprecated\nItem 1 \n```\n\n**After**\n\n```jsx deprecated\n\n Item 1\n \n```\n\n## Default example\n\n```jsx live deprecated\nThis is a BorderBox \n```\n\nNote that `BorderBox` has default props set for `borderWidth`, `borderStyle`, and `borderColor`. This means that you cannot use `border={0} borderBottom={1}` or similar patterns; instead, use individual properties like `borderWidth={0} borderBottomWidth={1}`.\n\n## System props\n\nBorderBox components get `COMMON`, `LAYOUT`, `BORDER`, and `FLEX` system props. Read our [System Props](/system-props) doc page for a full list of available props.\n\n## Component props\n\n| Prop name | Type | Default | Description |\n| :----------- | :--------------- | :---------------------------: | :------------------------------------------------------------ |\n| borderWidth | String | '1px' | Sets the border, use theme values or provide your own. |\n| borderStyle | String | 'solid' | Sets the border style, use theme values or provide your own. |\n| borderColor | String | 'border.primary' (from theme) | Sets the border color, use theme values or provide your own. |\n| borderRadius | String or Number | 2 (from theme) | Sets the border radius, use theme values or provide your own. |\n| boxShadow | String | | Sets box shadow, use theme values or provide your own. |\n","parent":{"relativeDirectory":"deprecated","name":"BorderBox"}},{"fileAbsolutePath":"/home/runner/work/react/react/docs/content/deprecated/Buttons.mdx","frontmatter":{"title":"Button (legacy)"},"rawBody":"---\ntitle: Button (legacy)\nstatus: deprecated\nsource: https://github.com/primer/react/blob/main/src/Button\nstorybook: '/react/storybook?path=/story/composite-components-button--default-button'\n---\n\n## Deprecation\n\nUse [Button](/Button) instead.\n\nFor more info on the changes, have a look at the migration guide.\n[Button migration guide](/migration-guide/Button)\n\n`Button` is used for actions, like in forms, while `Link` is used for destinations, or moving from one page to another.\n\nIn special cases where you'd like to use a `` styled like a Button, use `` and provide an `href`.\n\nTo create a button group, wrap `Button` elements in the `ButtonGroup` element. `ButtonGroup` gets the same props as `Box`.\n\n## Examples\n\n### Kitchen sink\n\n```jsx live deprecated\n<>\n Button \n Button danger \n Button outline \n Button primary \n Button invisible \n window.alert('button clicked')} />\n\n \n Button \n Button \n Button \n \n\n Button table list \n\n```\n\n## Props\n\nNative `` HTML attributes are forwarded to the underlying React `button` component and are not listed below.\n\n\n \n\n## Status\n\n\n Color mode \n \n Dark \n High-contrast dark \n Light \n High-contrast light \n \n \n```\n\n### Using an onSelect handler\n\n```javascript live noinline deprecated\nconst WithOnSelectHandler = () => {\n const [selectedChoices, setSelectedChoices] = React.useState([])\n const choices = [\n {\n value: 'figma',\n displayName: 'Figma library',\n description: 'The Figma file where we have Figma symbols and light documentation'\n },\n {\n value: 'css',\n displayName: 'Primer CSS',\n description: 'The OG. A CSS library with utility styles and component styles'\n },\n {\n value: 'react',\n displayName: 'Primer React components',\n description: 'The React component library that these docs belong to'\n },\n {\n value: 'viewcomponents',\n displayName: 'Primer ViewComponents',\n description: 'The Rails and Web Components implementation of our components'\n }\n ]\n\n return (\n <>\n {\n setSelectedChoices(selectedValues)\n }}\n selected={selectedChoices}\n >\n Prefered Primer component interface \n \n Your choice won't be used for anything, this is just a React example\n \n \n {choices.map(choice => (\n \n {choice.displayName} \n {choice.description} \n \n ))}\n \n \n {selectedChoices.length ? (\n \n {choices.find(choice => choice.value === selectedChoices[0]).displayName} is your favorite? Ours too.\n \n ) : null}\n \n )\n}\n\nrender(\n Prefered Primer component interface \n\n \n Figma library \n Primer CSS \n Primer React components \n Primer ViewComponents \n \n \n```\n\n### Disabled\n\n```jsx live deprecated\n\n Color mode \n \n Dark \n High-contrast dark \n Light \n High-contrast light \n \n \n```\n\n### Required\n\n```jsx live deprecated\n\n Color mode \n \n Dark \n High-contrast dark \n Light \n High-contrast light \n \n \n```\n\n### With pre-selected choices\n\n```jsx live deprecated\n\n Prefered Primer component interface \n\n \n Figma library \n Primer CSS \n Primer React components \n Primer ViewComponents \n \n \n```\n\n### With validation\n\n```javascript live noinline deprecated\nconst choices = [\n {\n value: 'figma',\n displayName: 'Figma library',\n description: 'The Figma file where we have Figma symbols and light documentation'\n },\n {\n value: 'css',\n displayName: 'Primer CSS',\n description: 'The OG. A CSS library with utility styles and component styles'\n },\n {\n value: 'react',\n displayName: 'Primer React components',\n description: 'The React component library that these docs belong to'\n },\n {\n value: 'viewcomponents',\n displayName: 'Primer ViewComponents',\n description: 'The Rails and Web Components implementation of our components'\n }\n]\n\nconst ChoiceFieldsetWithValidation = () => {\n const [selectedChoices, setSelectedChoices] = React.useState([])\n const [validationResult, setValidationResult] = React.useState()\n\n React.useEffect(() => {\n if (selectedChoices.length && selectedChoices.length > 2) {\n setValidationResult('tooManySelections')\n } else {\n setValidationResult(undefined)\n }\n }, [selectedChoices])\n\n return (\n {\n setSelectedChoices(selectedValues)\n }}\n validationMap={{tooManySelections: 'error'}}\n validationResult={validationResult}\n selected={selectedChoices}\n >\n Prefered Primer component interface \n Pick your top two \n\n \n {choices.map(choice => (\n \n {choice.displayName} \n {choice.description} \n \n ))}\n \n\n \n Only two selections are allowed\n \n \n )\n}\n\nrender(\n Color mode \n \n Dark \n High-contrast dark \n Light \n High-contrast light \n \n \n```\n\n### With a ChoiceFieldset.Description\n\n```jsx live deprecated\n\n Notification preferences \n \n Your selection will affect notifications sent to your email and mobile device\n \n\n \n \n \n \n All notifications \n Every possible notification \n \n \n \n \n Relevant notifications \n Only the ones you'll care about \n \n \n \n \n No notifications \n Notifications won't be sent \n \n \n \n```\n\n### With one disabled item\n\n```jsx live deprecated\n\n Color mode \n \n \n Dark\n \n High-contrast dark \n Light \n High-contrast light \n \n \n```\n\n### Items with a caption and a leading visual\n\n```jsx live deprecated\n\n Notification preferences \n\n \n \n \n \n All notifications \n Every possible notification \n \n \n \n \n Relevant notifications \n Only the ones you'll care about \n \n \n \n \n No notifications \n Notifications won't be sent \n \n \n \n```\n\n## Props\n\n### ChoiceFieldset\n\n| Name | Type | Default | Description |\n| :--------------- | :-------------------------------------------------------------------------------------------------------- | :-----: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| children\\* | `ChoiceFieldset.Legend`, `ChoiceFieldset.Description`, `ChoiceFieldset.List`, `ChoiceFieldset.Validation` | – | The list of choices and contextual information |\n| disabled | `boolean` | – | Whether the fieldset is NOT ready for user input |\n| id | `string` | – | The unique identifier for this fieldset. Used to associate the validation text with the fieldset ` | – | A map of validation statuses and their associated validation keys. When one of the validation keys is passed to the `validationResult` prop, the associated validation message will be rendered in the correct style |\n| validationResult | `keyof validationMap` | – | The key of the validation message to show |\n\n### ChoiceFieldset.Legend\n\nA title for the set of choices. A `ChoiceFieldset.Legend` must be passed, but it may be visually hidden.\n\n| Name | Type | Default | Description |\n| :------------- | :-------- | :-----: | :------------------------------------------- |\n| visuallyHidden | `boolean` | – | Whether to visually hide the fieldset legend |\n\n### ChoiceFieldset.List\n\nThe list choices are rendered in.\n\n| Name | Type | Default | Description |\n| :--------------- | :--------------------- | :-----: | :------------------------------------------------------ |\n| children\\* | `ChoiceFieldset.Item` | – | The choices that render as a checkbox or radio field |\n| selectionVariant | `'single'\\|'multiple'` | – | Whether multiple items or a single item can be selected |\n\n### ChoiceFieldset.Item\n\nRenders a choice to the list as a checkbox or radio field.\n\n| Name | Type | Default | Description |\n| :--------- | :-------------------------------------------------------------------------------------------------- | :-----: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| children\\* | `ChoiceFieldset.Caption`, `ChoiceFieldset.Label`, `ChoiceFieldset.LeadingVisual`, `React.ReactNode` | – | The parts that make up the checkbox or radio field used to select the choice. \n Option one \n \n```\n\n### Radio\n\n```jsx live deprecated\n\n \n Option one \n \n \n Option two \n \n \n```\n\n### Disabled field\n\n```jsx live deprecated\n\n Option one \n \n```\n\n### With a caption\n\n```jsx live deprecated\n\n Option One \n Hint: the first and only option \n \n```\n\n### With a LeadingVisual\n\n```jsx live deprecated\n<>\n \n Option one \n \n \n \n\n \n Option two \n \n \n This one has a caption \n \n\n```\n\n## Props\n\n### ChoiceInputField\n\nThe container that handles the layout and passes the relevant IDs and ARIA attributes it's children.\n\n`ChoiceInputField.Label` and `ChoiceInputField.Input` are required children.\n\n\n \n\n### ChoiceInputField.Label\n\nA `ChoiceInputField.Label` must be passed, but it may be visually hidden.\n\n\n \n\n### ChoiceInputField.Caption\n\nIf this field needs additional context, a `ChoiceInputField.Caption` may be used to render hint text.\n\n\n \n\n### ChoiceInputField.LeadingVisual\n\nIf the selectable option would be easier to understand with a visual, the `ChoiceInputField.LeadingVisual` component may be used.\n\n\n \n\n## Status\n\n\n Dropdown \n \n Item 1 \n Item 2 \n Item 3 \n \n \n```\n\n## With custom button\n\n```jsx live deprecated\n\n \n Dropdown\n \n \n Item 1 \n Item 2 \n Item 3 \n \n \n```\n\n## Component props\n\nThe Dropdown component is extended from the [`Details`](/Details) component and gets all props that the [`Details`](/Details) component gets.\n\n#### Dropdown.Menu\n\n| Name | Type | Default | Description |\n| :-------- | :---------------- | :-----: | :------------------------------------------------------------------------------------ |\n| direction | String | 'sw' | Sets the direction of the dropdown menu. Pick from 'ne', 'e', 'se', 's', 'sw', or 'w' |\n| sx | SystemStyleObject | {} | Style to be applied to the component |\n\n#### Dropdown.Button\n\nSee https://primer.style/react/Buttons#component-props\n\n#### Dropdown.Caret\n\n| Name | Type | Default | Description |\n| :--- | :---------------- | :-----: | :----------------------------------- |\n| sx | SystemStyleObject | {} | Style to be applied to the component |\n\n#### Dropdown.Item\n\n| Name | Type | Default | Description |\n| :--- | :---------------- | :-----: | :----------------------------------- |\n| sx | SystemStyleObject | {} | Style to be applied to the component |\n","parent":{"relativeDirectory":"deprecated","name":"Dropdown"}},{"fileAbsolutePath":"/home/runner/work/react/react/docs/content/deprecated/DropdownMenu.mdx","frontmatter":{"title":"DropdownMenu"},"rawBody":"---\ntitle: DropdownMenu\nstatus: Deprecated\n---\n\nA `DropdownMenu` provides an anchor (button by default) that will open a floating menu of selectable items. The menu can be opened and navigated using keyboard or mouse. When an item is selected, the menu will close and the `onChange` callback will be called. If the default anchor button is used, the anchor contents will be updated with the selection.\n\n## Deprecation\n\nUse [new version of ActionMenu](/ActionMenu#with-selection) with composable API, design updates and accessibility fixes.\n\n**Before**\n\n```jsx\nconst fieldTypes = [\n {key: 0, text: 'Text'},\n {key: 1, text: 'Number'},\n {key: 3, text: 'Date'},\n {key: 4, text: 'Single select'},\n {key: 5, text: 'Iteration'}\n]\n\nconst Example = () => {\n const [selectedType, setSelectedType] = React.useState()\n\n return (\n (\n \n {children} \n )}\n placeholder=\"Field type\"\n items={fieldTypes}\n selectedItem={selectedType}\n onChange={setSelectedType}\n />\n )\n}\n```\n\n**After**\n\nInstead of `DropdownMenu`, you can use the `ActionMenu` with `ActionList selectionVariant=single`, this will give menu items the correct semantics:\n\n```jsx\nconst fieldTypes = [\n {id: 0, text: 'Text'},\n {id: 1, text: 'Number'},\n {id: 3, text: 'Date'},\n {id: 4, text: 'Single select'},\n {id: 5, text: 'Iteration'}\n]\n\nconst Example = () => {\n const [selectedType, setSelectedType] = React.useState()\n\n render(\n \n {selectedType.name || 'Field type'} \n \n \n {fieldTypes.map(type => (\n setSelectedType(type)}\n >\n {type.name}\n \n ))}\n \n \n \n )\n}\n```\n\nOr continue using deprecated API:\n\n```js\nimport {DropdownMenu} from '@primer/react/deprecated'\n```\n\n## Example\n\n```javascript live noinline deprecated\nfunction DemoComponent() {\n const items = React.useMemo(\n () => [\n {text: '🔵 Cyan', id: 5, key: 'cyan'},\n {text: '🔴 Magenta', key: 'magenta'},\n {text: '🟡 Yellow', key: 'yellow'}\n ],\n []\n )\n const [selectedItem, setSelectedItem] = React.useState()\n\n return (\n (\n \n {children}\n \n )}\n placeholder=\"🎨\"\n items={items}\n selectedItem={selectedItem}\n onChange={setSelectedItem}\n />\n )\n}\n\nrender(\n \n Item 1\n \n \n```\n\n**After**\n\n```jsx deprecated\n\n \n Item 1\n \n \n```\n\n## Default example\n\n```jsx deprecated live\n\n \n \n Item 1\n \n \n Item 2\n \n \n Item 3\n \n \n \n```\n\n## System props\n\nFlex components get `FLEX`, `COMMON`, and `LAYOUT` system props.\n\nRead our [System Props](/system-props) doc page for a full list of available props.\n\n## Component props\n\n`Flex` does not get any additional props other than the system props mentioned above.\n","parent":{"relativeDirectory":"deprecated","name":"Flex"}},{"fileAbsolutePath":"/home/runner/work/react/react/docs/content/deprecated/FormGroup.md","frontmatter":{"title":"FormGroup"},"rawBody":"---\ntitle: FormGroup\nstatus: Deprecated\n---\n\nAdds styles for multiple form elements used together.\n\n## Deprecation\n\nUse [FormControl](/FormControl) instead.\n\n## Default example\n\n```jsx live deprecated\n<>\n \n Example text \n \n\n \n Example text \n \n\n```\n\n## Component props\n\n### FormGroup\n\n| Name | Type | Default | Description |\n| :--- | :---------------- | :-----: | :----------------------------------- |\n| as | String | `div` | Sets the HTML tag for the component |\n| sx | SystemStyleObject | {} | Style to be applied to the component |\n\n### FormGroup.Label\n\n| Name | Type | Default | Description |\n| :------ | :---------------- | :-----: | :----------------------------------------------------------------------------- |\n| as | String | `label` | Sets the HTML tag for the component |\n| htmlFor | String | | The value of `htmlFor` needs to be the same as the `id` of the input it labels |\n| sx | SystemStyleObject | {} | Style to be applied to the component |\n","parent":{"relativeDirectory":"deprecated","name":"FormGroup"}},{"fileAbsolutePath":"/home/runner/work/react/react/docs/content/deprecated/Grid.md","frontmatter":{"title":"Grid"},"rawBody":"---\ntitle: Grid\nstatus: Deprecated\n---\n\nGrid is a component that exposes grid system props. See the [CSS Tricks Complete Guide to Grid](https://css-tricks.com/snippets/css/complete-guide-grid/) to learn more about Grid Layout.\n\n## Deprecation\n\nUse [Box](/Box) instead.\n\n**Before**\n\n```jsx deprecated\n\n \n 1\n \n \n 2\n \n \n```\n\n**After**\n\n```jsx deprecated\n\n \n 1\n \n \n 2\n \n \n```\n\n## Default example\n\n```jsx deprecated live\n\n \n 1\n \n \n 2\n \n \n```\n\n## System props\n\nGrid components get `GRID`, `COMMON`, and `LAYOUT` system props.\n\nRead our [System Props](/system-props) doc page for a full list of available props.\n\n## Component props\n\n`Grid` does not get any additional props other than the system props mentioned above.\n","parent":{"relativeDirectory":"deprecated","name":"Grid"}},{"fileAbsolutePath":"/home/runner/work/react/react/docs/content/deprecated/InputField.mdx","frontmatter":{"title":"InputField"},"rawBody":"---\ntitle: InputField\nstatus: Deprecated\ndescription: The InputField component is used to render a labelled text input and, optionally, associated validation text and hint text.\nsource: https://github.com/primer/react/blob/main/src/InputField/InputField.tsx\nstorybook: '/react/storybook?path=/story/forms-inputfield--text-input-field'\n---\n\nimport {TextInputWithTokens, Autocomplete, Select} from '@primer/react'\n\n## Deprecation\n\nUse [FormControl](/FormControl) instead.\n\n## Examples\n\n### Basic\n\n```jsx live deprecated\n\n Name \n \n```\n\n### Required\n\n```jsx live deprecated\n\n Name \n \n```\n\n### Disabled\n\n```jsx live deprecated\n\n Name \n \n```\n\n### Using different input components\n\n```javascript live noinline deprecated\nconst TextInputWithTokensExample = () => {\n const [tokens, setTokens] = React.useState([\n {text: 'zero', id: 0},\n {text: 'one', id: 1},\n {text: 'two', id: 2}\n ])\n const onTokenRemove = tokenId => {\n setTokens(tokens.filter(token => token.id !== tokenId))\n }\n\n return (\n * + *': {\n marginTop: 4\n }\n }}\n >\n \n TextInputWithTokens \n \n \n Autocomplete \n \n \n \n \n \n \n Select \n \n Figma \n Primer CSS \n Primer React components \n Primer ViewComponents \n \n \n \n )\n}\n\nrender(TextInputWithTokensExample)\n```\n\n### With a visually hidden label\n\n\n\nEvery input must have a corresponding label to be accessible to assistive technology. That's why you'd use `InputField` instead of using [`TextInput`](/TextInput) directly.\n\n`InputField` also provides an interface for showing a hint text caption and a validation message, and associating those with the input for assistive technology.\n\n \n\n```jsx live deprecated\n\n Name \n \n```\n\n### With a caption\n\n```jsx live deprecated\n\n Name \n Hint: your first name \n \n```\n\n### With validation\n\n```javascript live noinline deprecated\nconst ValidationExample = () => {\n const [value, setValue] = React.useState('mona lisa')\n const [validationResult, setValidationResult] = React.useState()\n const doesValueContainSpaces = inputValue => /\\s/g.test(inputValue)\n const handleInputChange = e => {\n setValue(e.currentTarget.value)\n }\n\n React.useEffect(() => {\n if (doesValueContainSpaces(value)) {\n setValidationResult('noSpaces')\n } else if (value) {\n setValidationResult('validName')\n }\n }, [value])\n\n return (\n \n GitHub handle \n GitHub handles cannot contain spaces \n Valid name \n With or without \"@\". For example \"monalisa\" or \"@monalisa\" \n \n )\n}\n\nrender(ValidationExample)\n```\n\n## Props\n\n### InputField\n\nThe container that handles the layout and passes the relevant IDs and ARIA attributes it's children.\n\n\n \"\n description=\"A map of validation statuses and their associated validation keys. When one of the validation keys is passed to the `validationResult` prop, the associated validation message will be rendered in the correct style\"\n />\n \n\n### InputField.Label\n\nA `InputField.Label` must be passed for the field to be accessible to assistive technology, but it may be visually hidden.\n\n\n \n\n### InputField.Caption\n\n`InputField.Caption` may be used to render hint text for fields that require additional context.\n\n\n \n\n### InputField.Validation\n\n`InputField.Validation` may be used to render contextual validation information if the field was flagged during validation.\n\n\n \n\n## Component status\n\n\n small\n \n \n medium (default)\n \n \n large\n \n xl label \n\n \n good first issue\n \n \n 🚂 deploy: train\n \n \n css\n \n \n documentation\n \n \n primer\n \n\n```\n\n## Props\n\n\n \n\n## Status\n\n... \n ... \n ... \n ... \n ... \n\n```\n\n**After**\n\n```jsx deprecated\n<>\n ... \n ... \n ... \n ... \n ... \n\n```\n\n## Default examples\n\n```jsx deprecated live\n\n Relative + Absolute \n \n \n \n rt\n \n \n lt\n \n \n rb\n \n \n lb\n \n \n bl\n \n \n br\n \n \n tl\n \n \n tr\n \n \n \n\n Sticky \n\n \n \n I'm sticky!\n \n \n\n Fixed \n (see the bottom right of the screen)
\n\n \n I'm fixed to the bottom right.\n \n \n```\n\n## System props\n\nPosition components get `POSITION`, `LAYOUT`, `FLEX`, and `COMMON` system props. Read our [System Props](/system-props) doc page for a full list of available props.\n\n## Component props\n\nPosition does not get any additional props other than the system props mentioned above.\n","parent":{"relativeDirectory":"deprecated","name":"Position"}},{"fileAbsolutePath":"/home/runner/work/react/react/docs/content/deprecated/SelectMenu.md","frontmatter":{"title":"SelectMenu"},"rawBody":"---\ntitle: SelectMenu\nstatus: Deprecated\n---\n\n## Deprecation\n\nUse [ActionMenu](/ActionMenu) instead.\n\n---\n\nThe `SelectMenu` components are a suite of components which can be combined together to make several different variations of our GitHub select menu. At it's most basic form, a select menu is comprised of a `SelectMenu` wrapper, which contains a `summary` component of your choice and a `Select.Modal` which contains the select menu content. Use `SelectMenu.List` to wrap items in the select menu, and `SelectMenu.Item` to wrap each item.\n\nSeveral additional components exist to provide even more functionality: `SelectMenu.Header`, `SelectMenu.Filter`, `SelectMenu.Tabs`, `SelectMenu.TabPanel` `SelectMenu.Footer` and `SelectMenu.Divider`.\n\n## Basic Example\n\n```jsx deprecated live\n\n Projects \n \n Projects \n \n Primer React bugs \n Primer React roadmap \n Project 3 \n Project 4 \n \n \n \n```\n\n## SelectMenu\n\nMain wrapper component for select menu.\n\n```jsx deprecated\n{/* all other sub components are wrapped here*/} \n```\n\n### Component Props\n\n| Name | Type | Default | Description |\n| :--------- | :---------------- | :-----: | :--------------------------------------------------------------------------------------------------------------------------------------- |\n| initialTab | String | | If using the `SelectMenu.Tabs` component, you can use this prop to change the tab shown on open. By default, the first tab will be used. |\n| ref | React ref | | ref to pass down to SelectMenu component |\n| sx | SystemStyleObject | {} | Style to be applied to the component |\n\n## SelectMenu.MenuContext\n\nSelectMenu.MenuContext is a [context object](https://reactjs.org/docs/context.html#reactcreatecontext) that exposes some helpful state values to be used via [`React.useContext`](https://reactjs.org/docs/hooks-reference.html#usecontext) in consuming applications. SelectMenu.MenuContext can only be used in components that are already wrapped in a `SelectMenu` as `SelectMenu` contains the [context provider](https://reactjs.org/docs/context.html#contextprovider).\n\n### Values available on MenuContext\n\n| Name | Type | Description |\n| :------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------- |\n| selectedTab | string | The currently selected tab |\n| setSelectedTab | function | Used to update the currently selected tab state |\n| open | boolean | State for open/closed status of the menu modal |\n| setOpen | function | Used to update the `open` state |\n| initialTab | string | Mostly used internally to pass down which tab should be set to open by default. To change this value use the `initialTab` prop on `SelectMenu`. |\n\n### Example Usage\n\n```jsx deprecated\nimport {SelectMenu, Button} from `@primer/react`\nimport React, {useContext} from 'react'\n\nconst MyMenu = () => {\n \n \n content\n \n \n}\n\n// note that we can only use the context in components that are already wrapped by SelectMenu (and thus the Context.Provider)\nconst MyButton = () => {\n const menuContext = useContext(SelectMenu.MenuContext);\n\n return (\n {menuContext.open ? 'Open' : 'Closed'} \n )\n}\n```\n\n## SelectMenu.Modal\n\nUsed to wrap the content in a `SelectMenu`.\n\n```jsx deprecated\n{/* all menu content is wrapped in the modal*/} \n```\n\n### Right-aligned modal\n\nUse the `align='right'` prop to align the modal to the right. Note that this only modifies alignment for the modal, and not the SelectMenu itself. You will need to wrap the SelectMenu in a relatively positioned element for this to work properly.\n\n```jsx deprecated live\n\n \n Projects \n \n Projects \n \n Primer React bugs \n Primer React roadmap \n Project 3 \n Project 4 \n \n \n \n \n```\n\n### Component Props\n\n| Prop name | Type | Default | Description |\n| :-------- | :---------------- | :------ | ------------------------------------------------- |\n| align | String | 'left' | Use `right` to align the select menu to the right |\n| width | String or Number | 300px | Sets the modal width |\n| sx | SystemStyleObject | {} | Style to be applied to the component |\n\n## SelectMenu.List\n\nUsed to wrap the select menu list content. All menu items **must** be wrapped in a SelectMenu.List in order for the accessibility keyboard handling to function properly. If you are using the `SelectMenu.TabPanel` you do not need to provide a `SelectMenu.List` as that component renders a `SelectMenu.List` as a wrapper.\n\n```jsx deprecated\n{/* all menu list items are wrapped in the list*/} \n```\n\n### Component Props\n\n| Name | Type | Default | Description |\n| :--- | :---------------- | :-----: | :----------------------------------- |\n| sx | SystemStyleObject | {} | Style to be applied to the component |\n\n## SelectMenu.Item\n\nIndividual items in a select menu. SelectMenu.Item renders an anchor tag by default, you'll need to make sure to provide the appropriate `href`.\n\nYou can use a `button` tag instead by utilizing the [`as` prop](/core-concepts#the-as-prop). Be sure to consider [which HTML element is the right choice](https://marcysutton.com/links-vs-buttons-in-modern-web-applications) for your usage of the component.\n\n```jsx deprecated\n\n {/* wraps an individual list item*/}\n \n```\n\n### Component Props\n\n| Name | Type | Default | Description |\n| :------- | :---------------- | :-----: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| selected | boolean | | Used to apply styles to the selected items in the list. |\n| onClick | function | | Function called when item is clicked. By default we also close the menu when items are clicked. If you would like the menu to stay open, pass an `e.preventDefault()` to your onClick handler. |\n| sx | SystemStyleObject | {} | Style to be applied to the component |\n\n## SelectMenu.Filter\n\nUse a `SelectMenu.Filter` to add a filter UI to your select menu. Users are expected to implement their own filtering and manage the state of the `value` prop on the input. This gives users more flexibility over the type of filtering and type of content passed into each select menu item.\n\n```jsx deprecated live\n\n Projects \n \n Filter by Project \n \n Primer React bugs \n Primer React roadmap \n More Options \n Project 3 \n Project 4 \n \n \n \n```\n\n### Component Props\n\nSelectMenu.Filter components receive all the props that the [TextInput](/TextInput) component gets.\n\n| Name | Type | Default | Description |\n| :---- | :---------------- | :-----: | :------------------------------------------------------------------------------------------------------------- |\n| value | String | | Users of this component must provide a value for the filter input that is managed in the consuming application |\n| sx | SystemStyleObject | {} | Style to be applied to the component |\n\n## SelectMenu.Tabs\n\nUse `SelectMenu.Tabs` to wrap the tab navigation and `SelectMenu.Tab` for each tab in the navigation.\n\n`SelectMenu.TabPanel` should wrap each corresponding panel for each of the tabs. The `tabName` prop for each `SelectMenu.TabPanel` must match the name provided in the `tabName` prop on `SelectMenu.Tab`.\n\nTo set one of the tabs to be open by default, use `initialTab` on the main `SelectMenu` component. Otherwise, the first tab will be shown by default.\n\nEach `Select.Menu` tab will need to have an `index` prop. The first tab should be at index `0`, the second at index `1` and so forth. The `index` prop is used to show the first tab by default.\n\nIf you need access to the selected tab state, you can find it in the MenuContext object exported from `SelectMenu` as `MenuContext.selectedTab`.\n\n```jsx deprecated live\n\n Projects \n \n Projects \n \n \n \n Primer React bugs \n Primer React roadmap \n Project 3 \n Project 4 \n \n \n Project 2 \n \n Showing 3 of 3 \n \n \n```\n\n### Component Props\n\n| Name | Type | Default | Description |\n| :--- | :---------------- | :-----: | :----------------------------------- |\n| sx | SystemStyleObject | {} | Style to be applied to the component |\n\n## SelectMenu.Tab\n\nUsed for each individual tab inside of a `SelectMenu.Tabs`. Be sure to set the `index` prop to correspond to the order the tab is in. The `tabName` prop should correspond to the `tabName` set on the `SelectMenu.TabPanel`.\n\nThe `onClick` prop is optional and can be used for any events or data fetching you might need to trigger on tab clicks.\n\n```jsx deprecated\n<>\n {/* Wraps content for each tab */} \n```\n\n### Component Props\n\n| Name | Type | Default | Description |\n| :------ | :---------------- | :-----: | :------------------------------------------------------------------------------------------------------------------------- |\n| tabName | String | | Used to identify the corresponding tab. Must match the string used in the `tabs` array in the `SelectMenu.Tabs` component. |\n| sx | SystemStyleObject | {} | Style to be applied to the component |\n\n## SelectMenu.Divider\n\nUse a `SelectMenu.Divider` to add information between items in a `SelectMenu.List`.\n\n```jsx deprecated live\n\n Projects \n \n Projects \n \n Primer React bugs \n Primer React roadmap \n More Options \n Project 3 \n Project 4 \n \n \n \n```\n\n### Component Props\n\n| Name | Type | Default | Description |\n| :--- | :---------------- | :-----: | :----------------------------------- |\n| sx | SystemStyleObject | {} | Style to be applied to the component |\n\n## SelectMenu.Footer\n\nUse a `SelectMenu.Footer` to add content to the bottom of the select menu.\n\n```jsx deprecated live\n\n Projects \n \n Projects \n \n Primer React bugs \n Primer React roadmap \n Project 3 \n Project 4 \n Use ⌥ + click/return to exclude labels. \n \n \n \n```\n\n### Component Props\n\n| Name | Type | Default | Description |\n| :--- | :---------------- | :-----: | :----------------------------------- |\n| sx | SystemStyleObject | {} | Style to be applied to the component |\n\n## SelectMenu.Header\n\nUse a `SelectMenu.Header` to add a header to the top of the select menu content.\n\n```jsx deprecated live\n\n Projects \n \n Projects \n \n Primer React bugs \n Primer React roadmap \n Project 3 \n Project 4 \n Use ⌥ + click/return to exclude labels. \n \n \n \n```\n\n### Component Props\n\n| Name | Type | Default | Description |\n| :--- | :---------------- | :-----: | :----------------------------------- |\n| sx | SystemStyleObject | {} | Style to be applied to the component |\n\n## SelectMenu.LoadingAnimation\n\nUse a `SelectMenu.LoadingAnimation` to add a loading animation inside of the SelectMenu.\n\n**Note**: You will need to handle showing/hiding the appropriate modal content for your application during the loading state. We recommend always showing the `SelectMenu.Filter` and `SelectMenu.Header` (if used) and hiding the rest of the modal content during the loading state.\n\n```jsx deprecated live\n\n Projects \n \n Projects \n \n Primer React bugs \n Primer React roadmap \n Project 3 \n Project 4 \n Use ⌥ + click/return to exclude labels. \n \n )}\n \n \n```\n\n### Component Props\n\n| Name | Type | Default | Description |\n| :--- | :---------------- | :-----: | :----------------------------------- |\n| sx | SystemStyleObject | {} | Style to be applied to the component |\n","parent":{"relativeDirectory":"deprecated","name":"SelectMenu"}},{"fileAbsolutePath":"/home/runner/work/react/react/docs/content/drafts/Dialog.mdx","frontmatter":{"title":"Dialog v2"},"rawBody":"---\ntitle: Dialog v2\ncomponentId: dialog\nstatus: Draft\n---\n\n```js\nimport {Dialog} from '@primer/react/drafts'\n```\n\nimport State from '../../components/State'\n\nThe dialog component the Primer implementation of the ARIA design pattern [Dialog](https://www.w3.org/TR/wai-aria-practices-1.1/#dialog_modal). A dialog is a type of overlay that can be used for confirming actions, asking for disambiguation, and presenting small forms. They generally allow the user to focus on a quick task without having to navigate to a different page.\n\n**Dialogs appear in the page after a direct user interaction**. Don't show dialogs on page load or as system alerts.\n\n**Dialogs appear centered in the page**, with a visible backdrop that dims the rest of the window for focus.\n\n**All dialogs should have a title and a close button**. Use the `title` prop to set the title. The close button is created automatically, but must be handled with an `onClose` prop.\n\n**Dialogs are modal**. Dialogs can be dismissed by clicking on the close button, or by interacting with another button in the overlay. To avoid losing information and missing important messages, clicking outside of the dialog will not close it.\n\n**(Coming soon) Make sure larger dialogs remain mobile-friendly**. Even large dialogs need to be responsive. A dialog's width and height will be readjusted depending on the screen size and should never exceed the available space. Use responsive solutions to adjust the UI so they behave well on smaller screens.\n\n**(Coming soon) Simple and small dialogs can remain as-is on mobile**. As more elements are added to it, mobile-specific style variations such as **Bottom sheet** and **Full-screen** should be considered.\n\n### State\n\nThe dialog component is completely stateless. The parent component must conditionally render a dialog based on the necessary criteria. The parent component can be notified by a gesture to close the dialog (e.g. by clicking the \"X\" button or by pressing the Escape key) by passing in the `onClose` prop.\n\n### Accessibility\n\nThe dialog component is fully accessible out-of-the-box. The dialog's title is used for `aria-labelledby`, and the dialog's description is used for `aria-describedby`. The `aria-modal=\"true\"` attribute is used to inform screen readers that the rest of the content on the page is inert.\n\n#### Keyboard\n\nThe default keyboard API for a dialog employs three mechanisms:\n\n1. The Escape key can be pressed to close the dialog.\n2. Focus is trapped within the top-most dialog. When a dialog is opened, the close button receives initial focus by default, or on a button defined with `autoFocus: true`.\n3. If there are buttons in the dialog footer, focus can be moved between them with left and right arrow keys or tab/shift+tab.\n4. When a dialog is closed, it can optionally handle returning focus to the element that was focused immediately before the dialog was opened. Otherwise, it is the consumer's responsibility to move focus to a suitable element.\n\n### Custom rendering\n\n**Note: using custom rendering allows breaking out of the defined design, UX, and accessibility patterns of the dialog. Use only as a last resort.**\n\nBy default, the Dialog component implements the design and interactions defined by the Primer design system. If necessary, you can provide custom renderers for the header, body, or footer using the `renderHeader`, `renderBody`, and `renderFooter` props, respectively. The JSX produced by these render props will render full-bleed into their respective areas of the dialog. If you are using the custom renderers, you should use the provided sub-components `Dialog.Header`, `Dialog.Title`, `Dialog.Subtitle`, `Dialog.CloseButton`, `Dialog.Body`, `Dialog.Footer`, and `Dialog.Buttons` to the extent possible.\n\n### Example\n\n```jsx live drafts\n\n {([isOpen, setIsOpen]) => {\n const openDialog = React.useCallback(() => setIsOpen(true), [setIsOpen])\n const closeDialog = React.useCallback(() => setIsOpen(false), [setIsOpen])\n return (\n <>\n Open \n {isOpen && (\n \n This is a description of the dialog.\n \n }\n footerButtons={[{content: 'Ok', onClick: closeDialog}]}\n onClose={closeDialog}\n >\n Some content \n \n )}\n \n )\n }}\n \n```\n\n## Component props\n\n### DialogProps\n\n| Prop name | Type | Default | Description |\n| :------------ | :--------------------------------------------- | :--------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| title | `React.ReactNode` | `\"Dialog\"` | Sets the title of the dialog, which by default is also used as the `aria-labelledby` attribute. |\n| subtitle | `React.ReactNode` | | Optional. Sets the subtitle of the dialog, which by default is also used as the `aria-describedby` attribute. |\n| renderHeader | `(props: DialogHeaderProps) => JSX.Element` | | Optional. Custom render the dialog header. See \"Custom rendering\" above for more info. |\n| renderBody | `(props: DialogProps) => JSX.Element` | | Optional. Custom render the dialog body. See \"Custom rendering\" above for more info. |\n| renderFooter | `(props: DialogProps) => JSX.Element` | | Optional. Custom render the dialog footer. See \"Custom rendering\" above for more info. |\n| footerButtons | `DialogButtonProps[]` | | Optional. Specify buttons that will be rendered in the footer of the dialog. |\n| onClose | `(gesture: 'close-button' │ 'escape') => void` | | Required. 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'). |\n| role | `\"dialog\" │ \"alertdialog\"` | `\"dialog\"` | The ARIA role given to the dialog element. More info: [dialog](https://www.w3.org/TR/wai-aria-practices-1.1/#dialog_modal), [alertdialog](https://www.w3.org/TR/wai-aria-practices-1.1/#alertdialog) |\n| width | `\"small\" │ \"medium\" │ \"large\" │ \"xlarge\"` | `\"xlarge\"` | The fixed width of the dialog. |\n| height | `\"small\" │ \"large\" │ \"auto\"` | `\"auto\"` | The fixed height of the dialog, or, auto to adjust the height based on its contents. |\n| sx | `SystemStyleObject` | {} | Style to be applied to the component |\n\n### DialogHeaderProps\n\nThe `DialogHeaderProps` interface extends `DialogProps` and adds these additional properties:\n\n| Prop name | Type | Description |\n| :------------------ | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| dialogLabelId | `string` | ID of the element that will be used as the `aria-labelledby` attribute on the dialog. This ID should be set to the element that renders the dialog's title. |\n| dialogDescriptionId | `string` | ID of the element that will be used as the `aria-describedby` attribute on the dialog. This ID should be set to the element that renders the dialog's subtitle. |\n\n### DialogButtonProps\n\nThe `DialogButtonProps` interface extends `ButtonProps` (see Button) and adds these additional properties:\n\n| Prop name | Type | Default | Description |\n| :--------- | :-------------------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| buttonType | `\"normal\" │ \"primary\" │ \"danger\"` | `Button` | The type of button to render |\n| content | `React.ReactNode` | | Required. The button's inner content. |\n| autoFocus | `boolean` | false | If true, this button will be automatically focused when the dialog is first rendered. If `autoFocus` is true on subsequent button definitions, it will be ignored. |\n\n## ConfirmationDialog\n\nA `ConfirmationDialog` is a special kind of dialog with more rigid behavior. It is used to confirm a user action. `ConfirmationDialog`s always have exactly two buttons: one to cancel the action and one to confirm it. No custom rendering capabilities are provided for ConfirmationDialog.\n\n### useConfirm hook\n\nAn alternate way to use `ConfirmationDialog` is with the `useConfirm()` hook. It takes no parameters and returns an `async` function, `confirm`. When `confirm` is called (see ConfirmOptions below for its argument), it shows the confirmation dialog. When the dialog is dismissed, a promise is resolved with `true` or `false` depending on whether or not the confirm button was used.\n\n### Example (with `useConfirm` hook)\n\n```javascript live noinline\nfunction ShorthandExample2() {\n const confirm = useConfirm()\n const buttonClick = React.useCallback(\n async function (e) {\n if (await confirm({title: 'Are you sure?', content: 'You must confirm this action to continue.'})) {\n e.target.textContent = 'Confirmed!'\n }\n },\n [confirm]\n )\n return (\n <>\n Confirmable action \n \n )\n}\nrender(\n {([isOpen, setIsOpen]) => {\n const openDialog = React.useCallback(() => setIsOpen(true), [setIsOpen])\n const closeDialog = React.useCallback(() => setIsOpen(false), [setIsOpen])\n return (\n <>\n Open \n {isOpen && (\n \n Are you sure you want to confirm this action?\n \n )}\n \n )\n }}\n \n```\n\n### ConfirmationDialogProps\n\n| Prop name | Type | Default | Description |\n| :------------------- | :-------------------------------------------------------------------- | :--------- | :---------------------------------------------------------------------------------------------------------------------------- |\n| title | `React.ReactNode` | | Required. Sets the title of the dialog, which by default is also used as the `aria-labelledby` attribute. |\n| onClose | `(gesture: 'confirm' │ 'cancel' │ 'close-button' │ 'escape') => void` | | Required. This callback is invoked when a gesture to close the dialog is performed. The first argument indicates the gesture. |\n| cancelButtonContent | `React.ReactNode` | `\"Cancel\"` | The content to use for the cancel button. |\n| confirmButtonContent | `React.ReactNode` | `\"OK\"` | The content to use for the confirm button. |\n| confirmButtonType | `\"normal\" │ \"primary\" │ \"danger\"` | `Button` | The type of button to use for the confirm button. |\n\n### ConfirmOptions\n\n| Prop name | Type | Default | Description |\n| :------------------- | :-------------------------------- | :--------- | :-------------------------------------------------------------------------------------------------------- |\n| title | `React.ReactNode` | | Required. Sets the title of the dialog, which by default is also used as the `aria-labelledby` attribute. |\n| content | `React.ReactNode` | | Required. Used as the body of the ConfirmationDialog that is displayed. |\n| cancelButtonContent | `React.ReactNode` | `\"Cancel\"` | The content to use for the cancel button. |\n| confirmButtonContent | `React.ReactNode` | `\"OK\"` | The content to use for the confirm button. |\n| confirmButtonType | `\"normal\" │ \"primary\" │ \"danger\"` | `Button` | The type of button to use for the confirm button. |\n","parent":{"relativeDirectory":"drafts","name":"Dialog"}}]}}}