Drop

a container that is overlaid next to a target

Props

align

How to align the drop with respect to the target element. Not specifying a vertical or horizontal alignment will cause it to be aligned in the center.

To prevent creating a new object on each render, the align property should be persistent, either as a static constant outside of the render function or memo-ized using hooks.

For more guidance on when and how to memoize,read the React documentation on the useMemo hook. For using a static constant, see ourDrop component Storybook examples.

object

{
  top: "top" | "bottom",
  bottom: "top" | "bottom",
  right: "left" | "right",
  left: "left" | "right"
}
            

background

Either a color or identifier to use for the background color. For example: 'neutral-1'. Or, a 'url()' for an image. Dark is not needed if color is provided.

string

A color or image url.

"neutral-1"
"url(//my.com/assets/img.png)"
object

{
  color: "neutral-1",
  dark: true,
  image: "url(//my.com/assets/img.png)"
  position: "bottom",
  opacity: true,
  repeat: "no-repeat",
  size: "cover",
  light: "string",
  clip: "text",
  rotate: 45
}
              
{ dark: "light-2", light: "dark-2" }
where opacity could be:
"weak"
"medium"
"strong"
boolean
number
where position could be:
any CSS for background-position
where repeat could be:
"no-repeat"
"repeat"
"string"
where size could be:
"cover"
"contain"
"string"
where clip could be:
"text"
"border-box"
"padding-box"
"content-box"

elevation

Elevated height of the target, indicated via a drop shadow. Only applicable if the Drop isn't plain.

string
"none"
"xsmall"
"small"
"medium"
"large"
"xlarge"
"any custom elevation name in the current theme"

inline

By default, Drop is rendered using a React Portal, which places it outside the current DOM hierarchy as a child of the body. Sometimes, this isn't desireable and specifying inline indicates that it should be rendered directly as a child of its parent comoponent.

boolean
true
false

margin

The amount of margin around the component.

string
"none"
"xxsmall"
"xsmall"
"small"
"medium"
"large"
"xlarge"
object

Can be specified to distinguish horizontal margin, vertical margin, and margin on a particular side.


{
    vertical: "...",
    horizontal: "...",
    top: "...",
    bottom: "...",
    left: "...",
    right: "..."
}
        

onClickOutside

Function that will be invoked when the user clicks outside the drop.

function
() => {}

onEsc

Function that will be called when the user presses the escape key inside the drop.

function
() => {}

overflow

How to control the overflow inside the drop.

string
"auto"
"hidden"
"scroll"
"visible"
"string"
object

{
  horizontal: "...",
  vertical: "..."
}            
            

plain

Whether the drop element should have no background, elevation, margin or round.

boolean
true
false

responsive

Whether to dynamically re-place when resized.

boolean
true
false

restrictFocus

Whether the drop should control focus.

boolean
true
false

round

How much to round the corners.

boolean
true
false
string
"xsmall"
"small"
"medium"
"large"
"xlarge"
"full"
"string"
object

{
  corner: "...",
  size: "..."
}
            
where corner could be:
"top"
"left"
"bottom"
"right"
"top-left"
"top-right"
"bottom-left"
"bottom-right"

stretch

If set to true the drop element will be stretched to at least match the width of the target element. The default is true because that is what most uses of Drop want, like Select and Menu.

string

If set to align the width of the drop element will be restricted to the width of the target element.

"align"
boolean
true
false

target

Target where the drop will be aligned to.

object

This should be a React reference.

targetRef.current

trapFocus

Traps keyboard focus inside of drop.

boolean
true
false

React/DOM Properties

At its core, the Drop component is a regular <div> element. Thus, both DOM and React properties, methods, and events are accessible. To read up on all of the possible DOM attributes and types available for div elements, check out this MDN Web Documents page. To learn more about DOM events and methods, you can read more on the MDN Web Events documentation page.

Also, feel free to read about the types of React events available, or see how DOM attributes change in React. Working in tandem with Styled Components, you also have access to the as property.

Theme

drop.maxHeight

The max height of the Drop container.

string
"small"

global.drop.background

The background color of Drop.

string

A hex, name, or rgb value.

"white"
object

An object with a color for dark and light modes.

{ dark: "black", light: "white" }

global.drop.border.radius

The border radius of the Drop container.

string
"0px"

global.drop.extend

Any additional style for Drop.

string

Any CSS.

css`color: 'blue'`
function
(props) => {}

global.drop.intelligentMargin

Whether the margin of the Drop should adapt based on the Drop's alignment with respect to its target. Margin will only be applied on the side of the Drop that is adjacent to its target.

boolean
true
false

global.edgeSize

The possible sizes for the Drop margin.

object

    {
      none: '0px',
      hair: '1px',
      xxsmall: '3px',
      xsmall: '6px',
      small: '12px',
      medium: '24px',
      large: '48px',
      xlarge: '96px',
      responsiveBreakpoint: 'small'
    }
        

global.drop.elevation

Elevated height above the underlying context, indicated via a drop shadow.

string
"small"

global.drop.margin

The margin of the drop from the target.

string
"none"
"xxsmall"
"xsmall"
"small"
"medium"
"large"
"xlarge"
object

Can be specified to distinguish horizontal margin, vertical margin, and margin on a particular side.


{
    vertical: "...",
    horizontal: "...",
    top: "...",
    bottom: "...",
    left: "...",
    right: "..."
}
        

global.drop.shadowSize

Deprecated. Use 'global.drop.elevation' instead.

string
"small"

global.drop.zIndex

The stack order of the Drop.

number
20