or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-react-types--overlays

TypeScript type definitions for overlay components in React Spectrum design system

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@react-types/overlays@3.9.x

To install, run

npx @tessl/cli install tessl/npm-react-types--overlays@3.9.0

index.mddocs/

@react-types/overlays

@react-types/overlays provides comprehensive TypeScript type definitions for overlay components in React Spectrum, Adobe's design system. It defines interfaces and types for positioning overlays (modals, popovers, trays) including placement options, positioning properties, and trigger behaviors.

Package Information

  • Package Name: @react-types/overlays
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @react-types/overlays
  • Peer Dependencies: React ^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0-rc.1

Core Imports

import type { 
  Placement, 
  PositionProps, 
  ModalProps, 
  PopoverProps, 
  TrayProps,
  OverlayTriggerProps 
} from "@react-types/overlays";

For specific imports:

import type { Placement, PositionProps } from "@react-types/overlays";
import type { ModalProps } from "@react-types/overlays";

Basic Usage

import type { ModalProps, PopoverProps, Placement } from "@react-types/overlays";

// Define a modal component
function MyModal(props: ModalProps) {
  return (
    <div>
      {props.children}
    </div>
  );
}

// Define a popover component with placement
function MyPopover(props: PopoverProps & { placement: Placement }) {
  return (
    <div>
      {props.children}
    </div>
  );
}

// Usage with type safety
const modalProps: ModalProps = {
  children: <div>Modal content</div>,
  isOpen: true,
  onClose: () => console.log('closed'),
  type: 'modal',
  isDismissable: true
};

Architecture

@react-types/overlays is built around several key type categories:

  • Placement Types: Define where overlays appear relative to their anchors
  • Position Props: Control overlay positioning behavior and calculations
  • Component Props: Specific interfaces for modal, popover, and tray components
  • Trigger Props: Handle overlay open/close state management
  • Base Types: Foundation interfaces extended by specific component types

Capabilities

Placement Types

Core types for defining overlay positioning and placement relative to anchor elements.

type Placement = 
  | 'bottom' | 'bottom left' | 'bottom right' | 'bottom start' | 'bottom end'
  | 'top' | 'top left' | 'top right' | 'top start' | 'top end'
  | 'left' | 'left top' | 'left bottom' | 'start' | 'start top' | 'start bottom'
  | 'right' | 'right top' | 'right bottom' | 'end' | 'end top' | 'end bottom';

type Axis = 'top' | 'bottom' | 'left' | 'right';
type SizeAxis = 'width' | 'height';
type PlacementAxis = Axis | 'center';

Position Configuration

Interface for configuring overlay positioning behavior including placement, offsets, and flipping behavior.

interface PositionProps {
  /**
   * The placement of the element with respect to its anchor element.
   * @default 'bottom'
   */
  placement?: Placement;
  /**
   * The placement padding that should be applied between the element and its
   * surrounding container.
   * @default 12
   */
  containerPadding?: number;
  /**
   * The additional offset applied along the main axis between the element and its
   * anchor element.
   * @default 0
   */
  offset?: number;
  /**
   * The additional offset applied along the cross axis between the element and its
   * anchor element.
   * @default 0
   */
  crossOffset?: number;
  /**
   * Whether the element should flip its orientation (e.g. top to bottom or left to right) when
   * there is insufficient room for it to render completely.
   * @default true
   */
  shouldFlip?: boolean;
  /** Whether the element is rendered. */
  isOpen?: boolean;
}

Base Overlay Props

Base interface for all overlay components providing common functionality like lifecycle callbacks and focus management.

interface OverlayProps {
  children: ReactNode;
  isOpen?: boolean;
  container?: Element;
  isKeyboardDismissDisabled?: boolean;
  onEnter?: () => void;
  onEntering?: () => void;
  onEntered?: () => void;
  onExit?: () => void;
  onExiting?: () => void;
  onExited?: () => void;
  nodeRef: MutableRefObject<HTMLElement | null>;
  disableFocusManagement?: boolean;
  shouldContainFocus?: boolean;
}

Modal Props

Props interface for modal overlay components supporting different modal types and dismissal behavior.

interface ModalProps extends StyleProps, Omit<OverlayProps, 'nodeRef'> {
  children: ReactElement;
  isOpen?: boolean;
  onClose?: () => void;
  type?: 'modal' | 'fullscreen' | 'fullscreenTakeover';
  isDismissable?: boolean;
}

Popover Props

Props interface for popover overlay components with arrow support and placement options.

interface PopoverProps extends StyleProps, Omit<OverlayProps, 'nodeRef'> {
  children: ReactNode;
  placement?: PlacementAxis;
  arrowProps?: HTMLAttributes<HTMLElement>;
  hideArrow?: boolean;
  isOpen?: boolean;
  onClose?: () => void;
  shouldCloseOnBlur?: boolean;
  isNonModal?: boolean;
  isDismissable?: boolean;
}

Tray Props

Props interface for tray/drawer overlay components with height control and modal behavior options.

interface TrayProps extends StyleProps, Omit<OverlayProps, 'nodeRef'> {
  children: ReactElement;
  isOpen?: boolean;
  onClose?: () => void;
  shouldCloseOnBlur?: boolean;
  isFixedHeight?: boolean;
  isNonModal?: boolean;
}

Overlay Trigger Props

Props interface for components that trigger overlay open/close states with controlled and uncontrolled patterns.

interface OverlayTriggerProps {
  /** Whether the overlay is open by default (controlled). */
  isOpen?: boolean;
  /** Whether the overlay is open by default (uncontrolled). */
  defaultOpen?: boolean;
  /** Handler that is called when the overlay's open state changes. */
  onOpenChange?: (isOpen: boolean) => void;
}

Imported Types

// From React
import type { 
  HTMLAttributes, 
  MutableRefObject, 
  ReactElement, 
  ReactNode 
} from 'react';

// From @react-types/shared  
import type { StyleProps } from '@react-types/shared';

Type Dependencies

This package extends StyleProps from @react-types/shared, which provides comprehensive styling properties including:

  • Layout properties (margin, padding, width, height)
  • Flexbox and grid layout
  • Positioning and z-index
  • Border and background styling
  • Responsive design support
  • Accessibility and interaction states