@primer/components 32.1.0 → 33.0.0-rc.9f3670b7

package/docs/content/AvatarStack.mdx

@@ -0,0 +1,57 @@
+---
+title: AvatarStack
+status: Alpha
+description: Use an avatar stack to display two or more avatars in an inline stack.
+source: https://github.com/primer/react/blob/main/src/AvatarStack.tsx
+---
+
+import {AvatarStack} from '@primer/components'
+
+### Default example
+
+```jsx live
+<AvatarStack>
+  <Avatar alt="Primer" src="https://avatars.githubusercontent.com/primer" />
+  <Avatar alt="GitHub" src="https://avatars.githubusercontent.com/github" />
+  <Avatar alt="Atom" src="https://avatars.githubusercontent.com/atom" />
+  <Avatar alt="Desktop" src="https://avatars.githubusercontent.com/desktop" />
+</AvatarStack>
+```
+
+### Right aligned
+
+```jsx live
+<AvatarStack alignRight>
+  <Avatar alt="Primer" src="https://avatars.githubusercontent.com/primer" />
+  <Avatar alt="GitHub" src="https://avatars.githubusercontent.com/github" />
+  <Avatar alt="Atom" src="https://avatars.githubusercontent.com/atom" />
+  <Avatar alt="Desktop" src="https://avatars.githubusercontent.com/desktop" />
+</AvatarStack>
+```
+
+## Props
+
+| Name       | Type              | Default | Description                          |
+| :--------- | :---------------- | :-----: | :----------------------------------- |
+| alignRight | Boolean           |         | Creates right aligned AvatarStack    |
+| sx         | SystemStyleObject |   {}    | Style to be applied to the component |
+
+## Component status
+
+<ComponentChecklist
+  items={{
+    propsDocumented: true,
+    noUnnecessaryDeps: true,
+    adaptsToThemes: true,
+    adaptsToScreenSizes: true,
+    fullTestCoverage: false,
+    usedInProduction: true,
+    usageExamplesDocumented: true,
+    designReviewed: false,
+    a11yReviewed: false,
+    stableApi: false,
+    addressedApiFeedback: false,
+    hasDesignGuidelines: false,
+    hasFigmaComponent: false
+  }}
+/>

package/docs/content/BorderBox.md

@@ -0,0 +1,46 @@
+---
+title: BorderBox
+status: Deprecated
+---
+
+BorderBox is a Box component with a border. When no `borderColor` is present, the component defaults to a primary border.
+
+## Deprecation
+
+Use [Box](/Box) instead.
+
+**Before**
+
+```jsx
+<BorderBox>Item 1</BorderBox>
+```
+
+**After**
+
+```jsx
+<Box borderWidth="1px" borderStyle="solid" borderColor="border.default" borderRadius={2}>
+  Item 1
+</Box>
+```
+
+## Default example
+
+```jsx live
+<BorderBox>This is a BorderBox</BorderBox>
+```
+
+Note 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}`.
+
+## System props
+
+BorderBox components get `COMMON`, `LAYOUT`, `BORDER`, and `FLEX` system props. Read our [System Props](/system-props) doc page for a full list of available props.
+
+## Component props
+
+| Prop name    | Type             |            Default            | Description                                                   |
+| :----------- | :--------------- | :---------------------------: | :------------------------------------------------------------ |
+| borderWidth  | String           |             '1px'             | Sets the border, use theme values or provide your own.        |
+| borderStyle  | String           |            'solid'            | Sets the border style, use theme values or provide your own.  |
+| borderColor  | String           | 'border.primary' (from theme) | Sets the border color, use theme values or provide your own.  |
+| borderRadius | String or Number |        2 (from theme)         | Sets the border radius, use theme values or provide your own. |
+| boxShadow    | String           |                               | Sets box shadow, use theme values or provide your own.        |

package/docs/content/Box.mdx

@@ -0,0 +1,96 @@
+---
+title: Box
+status: Beta
+description: A low-level utility component that accepts styled system props to enable custom theme-aware styling
+source: https://github.com/primer/react/blob/main/src/Box.tsx
+---
+
+import {Props} from '../src/props'
+import {ComponentChecklist} from '../src/component-checklist'
+import {Box} from '@primer/components'
+
+```jsx live
+<Box color="fg.muted" bg="canvas.subtle" p={3}>
+  Hello
+</Box>
+```
+
+## Props
+
+<Props of={Box} />
+
+Box also accepts all [styled system props](https://styled-system.com/table/).
+
+## Examples
+
+### Border on all sides
+
+```jsx live
+<Box borderColor="border.default" borderWidth={1} borderStyle="solid" p={3}>
+  Hello
+</Box>
+```
+
+### Border on one side
+
+```jsx live
+<Box borderColor="border.default" borderBottomWidth={1} borderBottomStyle="solid" pb={3}>
+  Hello
+</Box>
+```
+
+### Flexbox
+
+Use Box to create [flexbox](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Flexbox) layouts.
+
+```jsx live
+<Box display="flex">
+  <Box p={3} borderColor="border.default" borderWidth={1} borderStyle="solid">
+    1
+  </Box>
+  <Box flexGrow={1} p={3} borderColor="border.default" borderWidth={1} borderStyle="solid">
+    2
+  </Box>
+  <Box p={3} borderColor="border.default" borderWidth={1} borderStyle="solid">
+    3
+  </Box>
+</Box>
+```
+
+### Grid
+
+Use Box to create [grid](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Grids) layouts.
+
+```jsx live
+<Box display="grid" gridTemplateColumns="1fr 1fr" gridGap={3}>
+  <Box p={3} borderColor="border.default" borderWidth={1} borderStyle="solid">
+    1
+  </Box>
+  <Box p={3} borderColor="border.default" borderWidth={1} borderStyle="solid">
+    2
+  </Box>
+  <Box p={3} borderColor="border.default" borderWidth={1} borderStyle="solid">
+    3
+  </Box>
+</Box>
+```
+
+## Component status
+
+<ComponentChecklist
+  items={{
+    propsDocumented: true,
+    noUnnecessaryDeps: true,
+    adaptsToThemes: true,
+    adaptsToScreenSizes: true,
+    fullTestCoverage: true,
+    usedInProduction: true,
+    usageExamplesDocumented: true,
+    designReviewed: null,
+    a11yReviewed: null,
+    stableApi: false,
+    addressedApiFeedback: false,
+    hasDesignGuidelines: null,
+    hasFigmaComponent: null
+  }}
+/>

package/docs/content/BranchName.md

@@ -0,0 +1,39 @@
+---
+title: BranchName
+status: Alpha
+source: https://github.com/primer/react/blob/main/src/BranchName.tsx
+---
+
+BranchName is a label-type component rendered as an `<a>` tag by default with monospace font.
+
+```jsx live
+<BranchName>a_new_feature_branch</BranchName>
+```
+
+## Props
+
+| Name | Type              | Default | Description                          |
+| :--- | :---------------- | :-----: | :----------------------------------- |
+| as   | String            |  `<a>`  | sets the HTML tag for the component  |
+| href | String            |         | a URL to link the component to       |
+| sx   | SystemStyleObject |   {}    | Style to be applied to the component |
+
+## Component status
+
+<ComponentChecklist
+items={{
+    propsDocumented: true,
+    noUnnecessaryDeps: true,
+    adaptsToThemes: true,
+    adaptsToScreenSizes: true,
+    fullTestCoverage: true,
+    usedInProduction: false,
+    usageExamplesDocumented: true,
+    designReviewed: false,
+    a11yReviewed: false,
+    stableApi: false,
+    addressedApiFeedback: false,
+    hasDesignGuidelines: false,
+    hasFigmaComponent: false
+  }}
+/>

package/docs/content/Breadcrumbs.md

@@ -0,0 +1,68 @@
+---
+title: Breadcrumbs
+status: Alpha
+description: Use breadcrumbs to show navigational context on pages that are many levels deep in a site’s hierarchy. Breadcrumbs show and link to parent, grandparent, and sometimes great-grandparent pages.
+source: https://github.com/primer/react/blob/main/src/Breadcrumbs.tsx
+---
+
+Breadcrumbs are used to show taxonomical context on pages that are many levels deep in a site’s hierarchy. Breadcrumbs show and link to parent, grandparent, and sometimes great-grandparent pages. Breadcrumbs are most appropriate on pages that:
+
+- Are many levels deep on a site
+- Do not have a section-level navigation
+- May need the ability to quickly go back to the previous (parent) page
+
+To use Breadcrumbs with [react-router](https://github.com/ReactTraining/react-router) or
+[react-router-dom](https://www.npmjs.com/package/react-router-dom), pass
+`as={NavLink}` and omit the `selected` prop.
+This ensures that the NavLink gets `activeClassName='selected'`
+
+## Default example
+
+```jsx live
+<Breadcrumbs>
+  <Breadcrumbs.Item href="/">Home</Breadcrumbs.Item>
+  <Breadcrumbs.Item href="/about">About</Breadcrumbs.Item>
+  <Breadcrumbs.Item href="/about/team" selected>
+    Team
+  </Breadcrumbs.Item>
+</Breadcrumbs>
+```
+
+## Props
+
+### Breadcrumbs
+
+| Prop name | Type              | Default | Description                          |
+| :-------- | :---------------- | :-----: | :----------------------------------- |
+| children  | ReactNode         |         | The `Breadcrumbs.Item`s              |
+| className | string            |         |                                      |
+| sx        | SystemStyleObject |  `{}`   | Style to be applied to the component |
+
+### Breadcrumbs.Item
+
+| Prop name | Type              | Default | Description                                      |
+| :-------- | :---------------- | :-----: | :----------------------------------------------- |
+| as        | string            |   `a`   | Sets the HTML tag for the component              |
+| href      | string            |         | URL to be used for the Link                      |
+| selected  | boolean           | `false` | Used to style the link as selected or unselected |
+| sx        | SystemStyleObject |  `{}`   | Style to be applied to the component             |
+
+## Component status
+
+<ComponentChecklist
+  items={{
+    propsDocumented: true,
+    noUnnecessaryDeps: true,
+    adaptsToThemes: true,
+    adaptsToScreenSizes: false,
+    fullTestCoverage: false,
+    usedInProduction: true,
+    usageExamplesDocumented: true,
+    designReviewed: false,
+    a11yReviewed: false,
+    stableApi: false,
+    addressedApiFeedback: false,
+    hasDesignGuidelines: false,
+    hasFigmaComponent: false
+  }}
+/>

package/docs/content/Buttons.md

@@ -0,0 +1,47 @@
+---
+title: Button
+status: Alpha
+---
+
+`Button` is used for actions, like in forms, while `Link` is used for destinations, or moving from one page to another.
+
+In special cases where you'd like to use a `<a>` styled like a Button, use `<Button as='a'>` and provide an `href`.
+
+To create a button group, wrap `Button` elements in the `ButtonGroup` element. `ButtonGroup` gets the same props as `Box`.
+
+## Default examples
+
+```jsx live
+<>
+  <Button>Button</Button>
+  <ButtonDanger>Button Danger</ButtonDanger>
+  <ButtonOutline>Button Outline</ButtonOutline>
+  <ButtonPrimary>Button Primary</ButtonPrimary>
+  <ButtonInvisible>Button Invisible</ButtonInvisible>
+  <ButtonClose onClick={() => window.alert('button clicked')} />
+
+  <ButtonGroup display="block" my={2}>
+    <Button>Button</Button>
+    <Button>Button</Button>
+    <Button>Button</Button>
+  </ButtonGroup>
+
+  <ButtonTableList>Button Table List </ButtonTableList>
+</>
+```
+
+## Component props
+
+Native `<button>` HTML attributes are forwarded to the underlying React `button` component and are not listed below.
+
+### Button
+
+| Prop name | Type              | Default  | Description                                                                                                                 |
+| :-------- | :---------------- | :------: | :-------------------------------------------------------------------------------------------------------------------------- |
+| as        | String            | `button` | sets the HTML tag for the component                                                                                         |
+| sx        | SystemStyleObject |    {}    | Additional styles                                                                                                           |
+| variant   | String            | 'medium' | a value of `small`, `medium`, or `large` results in smaller or larger Button text size; no effect if `fontSize` prop is set |
+
+### ButtonGroup
+
+`ButtonGroup` has access to the same props as `Box`

package/docs/content/Checkbox.md

@@ -0,0 +1,118 @@
+---
+title: Checkbox
+description: Use checkboxes to toggle between checked and unchecked states in a list or as a standalone form field
+status: Alpha
+source: https://github.com/primer/react/blob/main/src/Checklist.tsx
+storybook: '/react/storybook?path=/story/forms-checkbox--default'
+---
+
+import {ComponentChecklist} from '../src/component-checklist'
+
+## Default example
+
+The `Checkbox` component can be used in controlled and uncontrolled modes.
+
+```jsx live
+<>
+  <Box as="form" sx={{p: 3, pt: 0, display: 'flex', alignItems: 'center'}}>
+    <Checkbox id="default-checkbox" />
+    <Text as="label" htmlFor="default-checkbox" sx={{fontSize: 2, fontWeight: 'bold', marginLeft: 1}}>
+      Default checkbox
+    </Text>
+  </Box>
+  <Box as="form" sx={{p: 3, display: 'flex', alignItems: 'center'}}>
+    <Checkbox id="always-checked-checkbox" checked={true} />
+    <Text as="label" htmlFor="always-checked-checkbox" sx={{fontSize: 2, fontWeight: 'bold', marginLeft: 1}}>
+      Always checked
+    </Text>
+  </Box>
+  <Box as="form" sx={{p: 3, display: 'flex', alignItems: 'center'}}>
+    <Checkbox id="always-unchecked-checkbox" checked={false} />
+    <Text as="label" htmlFor="always-unchecked-checkbox" sx={{fontSize: 2, fontWeight: 'bold', marginLeft: 1}}>
+      Always unchecked
+    </Text>
+  </Box>
+
+  <Box as="form" sx={{p: 3, display: 'flex', alignItems: 'center'}}>
+    <Checkbox id="inactive-checkbox" checked={true} disabled />
+    <Text as="label" htmlFor="inactive-checkbox" sx={{fontSize: 2, fontWeight: 'bold', marginLeft: 1}}>
+      Inactive
+    </Text>
+  </Box>
+</>
+```
+
+<Note variant="warning">
+Checkbox components should always be accompanied by a corresponding label to improve support for assistive technologies.
+</Note>
+
+## Indeterminate example
+
+An `indeterminate` checkbox state should be used if the input value is neither true nor false. This can be useful in situations where you are required to display an incomplete state, or one that is dependent on other input selections to determine a value.
+
+```jsx live
+<>
+  <Box as="form" sx={{p: 3, pt: 0, pb: 1, display: 'flex', alignItems: 'center'}}>
+    <Checkbox id="indeterminate-checkbox" onChange={() => {}} indeterminate={true} />
+    <Text as="label" sx={{fontSize: 2, fontWeight: 'bold', marginLeft: 1}} htmlFor="controlled-checkbox">
+      <Text sx={{display: 'block'}}>Default checkbox</Text>
+    </Text>
+  </Box>
+  <Box key={`sub-checkbox-0`} as="form" sx={{p: 1, pl: 6, display: 'flex', alignItems: 'center'}}>
+    <Checkbox id={`sub-checkbox-0`} checked={true} onChange={() => {}} />
+    <Text as="label" sx={{fontSize: 2, fontWeight: 'bold', marginLeft: 1}} htmlFor={`sub-checkbox-0`}>
+      <Text sx={{display: 'block'}}>Checkbox 1</Text>
+    </Text>
+  </Box>
+  <Box key={`sub-checkbox-1`} as="form" sx={{p: 1, pl: 6, display: 'flex', alignItems: 'center'}}>
+    <Checkbox id={`sub-checkbox-1`} checked={false} onChange={() => {}} />
+    <Text as="label" sx={{fontSize: 2, fontWeight: 'bold', marginLeft: 1}} htmlFor={`sub-checkbox-1`}>
+      <Text sx={{display: 'block'}}>Checkbox 2</Text>
+    </Text>
+  </Box>
+  <Box key={`sub-checkbox-2`} as="form" sx={{p: 1, pl: 6, display: 'flex', alignItems: 'center'}}>
+    <Checkbox id={`sub-checkbox-2`} checked={false} onChange={() => {}} />
+    <Text as="label" sx={{fontSize: 2, fontWeight: 'bold', marginLeft: 1}} htmlFor={`sub-checkbox-2`}>
+      <Text sx={{display: 'block'}}>Checkbox 3</Text>
+    </Text>
+  </Box>
+  <Box key={`sub-checkbox-3`} as="form" sx={{p: 1, pl: 6, display: 'flex', alignItems: 'center'}}>
+    <Checkbox id={`sub-checkbox-3`} checked={false} onChange={() => {}} />
+    <Text as="label" sx={{fontSize: 2, fontWeight: 'bold', marginLeft: 1}} htmlFor={`sub-checkbox-3`}>
+      <Text sx={{display: 'block'}}>Checkbox 4</Text>
+    </Text>
+  </Box>
+</>
+```
+
+## Component props
+
+Native `<input>` attributes are forwarded to the underlying React `input` component and are not listed below.
+
+| Name           | Type        |  Default  | Description                                                                                                                                             |
+| :------------- | :---------- | :-------: | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| checked        | Boolean     | undefined | Optional. Modifies true/false value of the native checkbox                                                                                              |
+| defaultChecked | Boolean     | undefined | Optional. Checks the input by default in uncontrolled mode                                                                                              |
+| onChange       | ChangeEvent | undefined | Optional. A callback function that is triggered when the checked state has been changed.                                                                |
+| disabled       | Boolean     | undefined | Optional. Modifies the native disabled state of the native checkbox                                                                                     |
+| indeterminate  | Boolean     | undefined | Optional. Applies an [indeterminate](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#attr-indeterminate) state to the checkbox |
+
+## Component status
+
+<ComponentChecklist
+items={{
+    propsDocumented: true,
+    noUnnecessaryDeps: true,
+    adaptsToThemes: true,
+    adaptsToScreenSizes: true,
+    fullTestCoverage: true,
+    usedInProduction: false,
+    usageExamplesDocumented: false,
+    designReviewed: false,
+    a11yReviewed: false,
+    stableApi: false,
+    addressedApiFeedback: false,
+    hasDesignGuidelines: false,
+    hasFigmaComponent: false
+  }}
+/>

package/docs/content/CircleBadge.md

@@ -0,0 +1,36 @@
+---
+title: CircleBadge
+status: Alpha
+---
+
+Use CircleBadge to visually connect logos of third party services like in marketplace. Use CircleBadge.Icon to add an Octicon to the CircleBadge.
+
+## Default example
+
+```jsx live
+<CircleBadge>
+  <CircleBadge.Icon icon={ZapIcon} />
+</CircleBadge>
+```
+
+## Component props
+
+### CircleBadge
+
+| Name    | Type    | Default  | Description                                                                                                 |
+| :------ | :------ | :------: | :---------------------------------------------------------------------------------------------------------- |
+| as      | String  |  `div`   | sets the HTML tag for the component                                                                         |
+| inline  | Boolean |  false   | Styles the badge to display inline                                                                          |
+| size    | Number  |          | sets the size of the badge in pixels; overrides any value for `variant` prop when set                       |
+| variant | String  | 'medium' | a value of `small`, `medium`, or `large` creates a smaller or larger badge; no effect if `size` prop is set |
+
+### CircleBadge.Icon
+
+CircleBadge.Icon components receive all the same props at [StyledOcticon]. They are listed below for convenience:
+
+| Name          | Type      |    Default    | Description                                                                                                  |
+| :------------ | :-------- | :-----------: | :----------------------------------------------------------------------------------------------------------- |
+| ariaLabel     | String    |               | Specifies the `aria-label` attribute, which is read verbatim by screen readers                               |
+| icon          | Component |               | [Octicon component](https://github.com/primer/octicons/tree/master/lib/octicons_react) used in the component |
+| size          | Number    |      16       | Sets the uniform `width` and `height` of the SVG element                                                     |
+| verticalAlign | String    | `text-bottom` | Sets the `vertical-align` CSS property                                                                       |

package/docs/content/CircleOcticon.md

@@ -0,0 +1,19 @@
+---
+title: CircleOcticon
+status: Alpha
+---
+
+CircleOcticon renders any Octicon with a circle background. CircleOcticons are most commonly used to represent the status of a pull request in the comment timeline.
+
+## Default example
+
+```jsx live
+<CircleOcticon icon={CheckIcon} size={32} sx={{bg: 'success.fg', color: 'fg.onEmphasis'}} />
+```
+
+## Component props
+
+| Name | Type    | Default | Description                                       |
+| :--- | :------ | :-----: | :------------------------------------------------ |
+| icon | Octicon |         | Octicon component used in the component           |
+| size | Number  |   32    | used to set the width and height of the component |

package/docs/content/CounterLabel.md

@@ -0,0 +1,22 @@
+---
+title: CounterLabel
+status: Alpha
+---
+
+Use the CounterLabel component to add a count to navigational elements and buttons.
+
+## Default example
+
+```jsx live
+<>
+  <CounterLabel>12</CounterLabel>
+  <CounterLabel scheme="primary">13</CounterLabel>
+  <CounterLabel scheme="secondary">13</CounterLabel>
+</>
+```
+
+## Component props
+
+| Name   | Type   | Default | Description                                                                                                                                                                        |
+| :----- | :----- | :-----: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| scheme | String |         | Pass in 'primary' for a darker background and inverse text, or 'gray-light' for a lighter background and primary text. Omitting the scheme prop renders the default counter scheme |

package/docs/content/Details.md

@@ -0,0 +1,102 @@
+---
+title: Details
+status: Alpha
+---
+
+`Details` is a styled `details` element for use with the `useDetails` hook. The `useDetails` hook returns the `open` state, a `setOpen` function to manually change the open state, and **`getDetailsProps` which must be spread onto your `Details` element in order for `Details` to get receive the proper behaviors provided by the hook**. See Kent Dodd's article on this pattern [here](https://kentcdodds.com/blog/how-to-give-rendering-control-to-users-with-prop-getters).
+
+The `useDetails` hook also takes a few configuration options as parameters which are noted in the table below.
+
+You must use a `summary` element as your `Details` trigger button. To style your summary element like a [Button](./Button), you can use the `as` prop (see example below).
+
+It's also possible to use the `useDetails` hook with components other than the Primer `Details`, such as a custom `Details` or `Modal` wrapper in your consuming application. All that matters is that the outer element is a `details` and it contains a `summary` for the button that opens and closes the component, and that `getDetailsProps` is properly spread onto the component rendering your `details` element.
+
+```jsx live
+<State>
+  {([]) => {
+    const {getDetailsProps} = useDetails({closeOnOutsideClick: true})
+    return (
+      <Details {...getDetailsProps()}>
+        <Button as="summary">Hello</Button>
+        This is some content
+      </Details>
+    )
+  }}
+</State>
+```
+
+You can use the `open` state returned from the hook to conditionally render content:
+
+```jsx live
+<State>
+  {([]) => {
+    const {getDetailsProps, open} = useDetails({closeOnOutsideClick: true})
+    return (
+      <Details {...getDetailsProps()}>
+        <Button as="summary">{open ? 'open' : 'close'}</Button>
+        This is some content
+      </Details>
+    )
+  }}
+</State>
+```
+
+You can also manually show/hide the content using the `setOpen` function returned from the hook. This can be useful if you have action items in the content of the component such as confirmation buttons:
+
+```jsx live
+<State>
+  {([]) => {
+    const {getDetailsProps, setOpen} = useDetails({closeOnOutsideClick: true})
+    return (
+      <Details {...getDetailsProps()}>
+        <Button as="summary">Delete item</Button>
+        Are you sure?
+        <ButtonDanger onClick={() => setOpen(false)}>Yes I'm sure</ButtonDanger>
+      </Details>
+    )
+  }}
+</State>
+```
+
+In previous versions of Primer React Components, we allowed users to pass in a custom `onToggle` function. You can do this now by overriding the `onToggle` function returned in `getDetailsProps`. Please note that in most cases, you'll want the hook's handling of `onToggle` to be run as well, so that the internal state is properly updated. To do this, manually call the `onToggle` handler returned from `useDetails` before executing your custom `onToggle` code.
+
+```jsx live
+<State>
+  {([]) => {
+    const {getDetailsProps, open, setOpen} = useDetails({closeOnOutsideClick: true})
+    const {onToggle, ...detailsProps} = getDetailsProps()
+    const customToggle = e => {
+      onToggle(e)
+      window.alert('hi')
+    }
+    return (
+      <Details {...detailsProps} onToggle={customToggle}>
+        <Button as="summary">{open ? 'Open' : 'Closed'}</Button>
+        Hello World
+      </Details>
+    )
+  }}
+</State>
+```
+
+## Details props
+
+| Name | Type              | Default | Description                          |
+| :--- | :---------------- | :-----: | :----------------------------------- |
+| sx   | SystemStyleObject |   {}    | Style to be applied to the component |
+
+## `useDetails` hook configuration options
+
+| Name                | Type      | Default | Description                                                               |
+| :------------------ | :-------- | :-----: | :------------------------------------------------------------------------ |
+| defaultOpen         | Boolean   |         | Sets the initial open/closed state                                        |
+| closeOnOutsideClick | Boolean   |  false  | Sets whether or not element will close when the user clicks outside of it |
+| ref                 | React ref |         | optional ref to pass down to Details component                            |
+
+### Values returned by the `useDetails` hook
+
+| Name            | Type     | Description                                                                                                                                                                                                                              |
+| :-------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| open            | string   | Whether or not Details is currently open                                                                                                                                                                                                 |
+| setOpen         | function | Used to manually change the open state of the Details component                                                                                                                                                                          |
+| getDetailsProps | Object   | Contains an `onToggle` function, the `ref` to pass down to `Details` and the `open` attribute. In most cases, you won't need to interact with any of these values directly, but if you'd like to override any of these yourself you may. |