npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@asphalt-react/popover

v2.0.0-rc.11

Published

Popover

Downloads

469

Readme

Popover

npm

Popover is an interactive floating element that displays information related to an anchor element when the element is clicked. It represents the UI element as floating above the normal flow creating the "pop out" effect. Popover can contain a range of elements from simple strings to complex React designs.

Popover is a controlled component, it does not manage visibility state on it's own.

Popover requires a target element which acts as a pivot for the content. Popover supports multiple placement positions using which <Popover/> element can be positioned next to the target element in any direction.

Popover comes in 3 sizes small(s), medium(m) & large(l).

Usage

import React, { useState } from "react"
import { Popover } from "@asphalt-react/popover"
import { Button } from "@asphalt-react/button"

const App = () => {
  const [open, setOpen] = useState(false)

  return (
    <Popover
      open={open}
      target={<Button>Click Me</Button>}
      onOpenChange={setOpen}
    >
      <p>
        Hello there
      </p>
    </Popover>
  )
}

export default App

Building blocks

  1. Popover component comes with:

    • BasePopover
    • FocusManager
  2. BasePopover supports 3 sizes: small(s), medium(m) & large(l).

  3. FocusManager handles the focus management for Popover content.

Hooks

usePopover

Use the usePopover() hook to get all the prop getter functions and then spread them in the target & popover components. usePopover() takes props as parameter.

React hook which returns prop getter functions. Use these functions to generate prop objects for different components in Popover.

Arguments

usePopover accepts the following props:

  1. open
  2. placement
  3. outOfFlow
  4. flip
  5. size
  6. bezel
  7. focusTrap
  8. noOffset
  9. lowOffset
  10. mediumOffset
  11. highOffset
  12. onOpenChange
  13. stretch
  14. returnFocus

Getter functions

getTargetProps()

Use this function to create props for Target element of the Popover.

const { getTargetProps } = usePopover({ open: true, onOpenChange: setOpen });

<Button {...getTargetProps()}>
  Click me
</Button>

getPopoverProps()

Use this function to create props for Popover/floating component.

const { getPopoverProps } = usePopover({ open: true, onOpenChange: setOpen });

<BasePopover {...getPopoverProps()}>
  <p>
    Hello there!
  </p>
</BasePopover>

getFocusProps()

Use this function to create props for FocusManager component.

const { getFocusProps } = usePopover({ open: true, onOpenChange: setOpen });

<FocusManager {...getFocusProps()}>
  <BasePopover {...getPopoverProps()}>
    <p>
      Hello there!
    </p>
  </BasePopover>
<FocusManager>

Usage

import { BasePopover, usePopover, FocusManager } from "@asphalt-react/popover"

const App = () => {
  const [open, setOpen] = useState(false)

  const { getTargetProps, getPopoverProps, getFocusProps } = usePopover({
    open,
    onOpenChange: setOpen,
  })

  return (
    <div>
      <Button {...getTargetProps()}>Click me</Button>
      {open && (
        <FocusManager {...getFocusProps()}>
          <BasePopover open={open} {...getPopoverProps()}>
            <p>
              Lorem ipsum dolor sit amet
            </p>
          </BasePopover>
        </FocusManager>
      )}
    </div>
  )
}

export default App

Accessibility

  • Pressing Esc key or clicking anywhere outside the popover closes it.

  • Popover traps focus within its content, rotating the focus among its interactive elements.

  • The first interactive element receives focus by default when Popover opens.

Props

children

React node to render inside Popover.

| type | required | default | | ---- | -------- | ------- | | node | true | N/A |

target

Target node that triggers the Popover.

| type | required | default | | ---- | -------- | ------- | | node | true | N/A |

open

Decides the open state for Popover.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

size

Size of the Popover.

| type | required | default | | ---- | -------- | ------- | | enum | false | "m" |

bezel

Adds padding on all sides.

| type | required | default | | ---- | -------- | ------- | | bool | false | true |

placement

Placement of the Popover with respect to target node.

Popover supports multiple placements:

  • autoauto-startauto-end
  • toptop-starttop-end
  • bottombottom-startbottom-end
  • leftleft-startleft-end
  • rightright-startright-end

| type | required | default | | ---- | -------- | -------- | | enum | false | "bottom" |

focusOrder

The order in which focus cycles.

  • reference - Target element which acts as pivot for Popover.
  • floating - Popover wrapper element.
  • content - Content inside Popover wrapper.

By default it's value is ['content'] - Subsequent tabs will cycle through the tabbable contents of the Popover content.

If the value is set to ['floating', 'content'] - Includes floating element in focus cycle.

If the value is set to ['reference', 'content'] - Includes reference element in focus cycle.

  • If the value is set to ['reference', 'floating', 'content'] - tabs will cycle through the reference, floating & tabbable contents of the Popover content.

| type | required | default | | ----- | -------- | ----------- | | array | false | ["content"] |

initialFocus

Element to initially focus when Popover is opened. Can be either a number or a ref. Number is decided by the tabbable index as specified by the focusOrder.

| type | required | default | | ----- | -------- | ------- | | union | false | 0 |

outOfFlow

When Popover is added to a container with position: fixed and/or overflow: hidden, it creates a containing block with a stacking context which the Popover can't skip. In such scenarios, enabling outOfFlow will remove Popover from its parent's flow.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

flip

Flips the position of the floating element if there is space constraint in order to make it visible in viewport.

| type | required | default | | ---- | -------- | ------- | | bool | false | true |

stretch

Enables the Popover to stretch and fill the width of its container. By default, the Popover matches the width of its content.

Strech works only in a relatively positioned container. Refer to the example below.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

shift

Shifts the Popover horizontally to avoid the content from overflowing the viewport.

| type | required | default | | ---- | -------- | ------- | | bool | false | true |

focusTrap

Add focus trap in the content, outside content cannot be accessed if enabled.

| type | required | default | | ---- | -------- | ------- | | bool | false | true |

lowOffset

adds a low spacing between target and Popover.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

mediumOffset

adds a medium spacing between target and Popover.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

highOffset

adds a high spacing between target and Popover.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

noOffset

removes spacing between target and Popover.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

onOpenChange

callback when open state is changed.

| type | required | default | | ---- | -------- | ------- | | func | false | null |

returnFocus

determines if focus should be returned to the reference element.

| type | required | default | | ---- | -------- | ------- | | bool | false | true |

BasePopover

Props

children

React node to render inside Base Popover.

| type | required | default | | ---- | -------- | ------- | | node | true | N/A |

open

Indicates the open state for Popover.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

size

Size of the Popover.

| type | required | default | | ---- | -------- | ------- | | enum | false | "m" |

bezel

Adds padding on all sides.

| type | required | default | | ---- | -------- | ------- | | bool | false | true |

stretch

Enables the Popover to stretch and fill the width of its container. By default, the Popover matches the width of its content.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

anchorStyles

Adds styles to position the Popover relative to the target element.

| type | required | default | | ------ | -------- | ------- | | object | false | N/A |

FocusManager

Props

children

React node to render inside Base Popover.

| type | required | default | | ---- | -------- | ------- | | node | true | N/A |

popoverContext

context object used to focus on the floating element, pass the popoverContext returned by the usePopover hook.

| type | required | default | | ------ | -------- | ------- | | object | true | N/A |

focusOrder

The order in which focus cycles.

  • reference - Target element which acts as pivot for Popover.
  • floating - Popover wrapper element.
  • content - Content inside Popover wrapper.

By default it's value is ['content'] - Subsequent tabs will cycle through the tabbable contents of the Popover content.

If the value is set to ['floating', 'content'] - Includes floating element in focus cycle.

If the value is set to ['reference', 'content'] - Includes reference element in focus cycle.

  • If the value is set to ['reference', 'floating', 'content'] - tabs will cycle through the reference, floating & tabbable contents of the Popover content.

| type | required | default | | ----- | -------- | ----------- | | array | false | ["content"] |

focusTrap

Add focus trap in the content, outside content cannot be accessed if enabled.

| type | required | default | | ---- | -------- | ------- | | bool | false | true |

initialFocus

Element to initially focus when Popover is opened. Can be either a number or a ref. Number is decided by the tabbable index as specified by the focusOrder.

| type | required | default | | ----- | -------- | ------- | | union | false | 0 |

returnFocus

determines if focus should be returned to the reference element.

| type | required | default | | ---- | -------- | ------- | | bool | false | true |