Typings

Popper comes with type definitions for both Flow and TypeScript.

The project is type checked by Flow, and type definitions for TypeScript are automatically generated from its source code.

Note, type definitions don't strictly follow SemVer, since any type change can be a breaking change, but type systems evolve very quickly and adjustments are constantly required to keep up with them.

Common (Flow and TypeScript)

This section covers common knowledge applicable to both Flow and TypeScript, for sake of simplicity the examples are written in Flow, but they should work as-is after the // @flow header has been removed.

Modifiers Type Checking

createPopper, by default, works in a loose-type mode, that means the modifiers are not strictly type-checked.

If you'd like to opt-in to the strict-mode, you can do the following:

// @flow
import { createPopper } from '@popperjs/core';
import type { StrictModifiers } from '@popperjs/core';

createPopper<StrictModifiers>(referenceElement, popperElement, options);

If you'd like to define custom modifiers, you will need to add them to the list:

// @flow
import { createPopper } from '@popperjs/core';
import type { StrictModifiers, Modifier } from '@popperjs/core';

type CustomModifier = Modifier<'custom', { customOption: boolean }>;
type ExtendedModifiers = StrictModifiers | $Shape<CustomModifier>;

createPopper<ExtendedModifiers>(referenceElement, popperElement, options);

Flow

Rather than exporting limited type definitions, we link to the Flow-typed source files from the dist/umd folder.

Flow will automatically read the exposed types, so you don't need to change any configuration in your project to take benefit from Popper typings.

You may also decide to import a specific module from the library, by doing so, the module types will be automatically imported with it:

import hideModifier from '@popperjs/core/lib/modifiers/hide';

It's although reccomended to add the following lines to your .flowconfig file in order to instruct Flow not to report type errors originating from your node_modules folder. Type definitions exposed by the modules will still be used, but their errors, if any, will be ignored.

[declarations]
<PROJECT_ROOT>/node_modules

TypeScript

Generating TypeScript type definitions from Flow makes it possible to type check the project with stricter rules, providing at the same time type definitions for users of other type system.

Type definition interfaces for the two type systems are inherently identical, but we can't guarantee the same level of type coverage for TypeScript definitions, due to the intrinsic differences between Flow and TypeScript.

TypeScript .d.ts files are colocated in the lib/ folder, together with the corresponding JavaScript modules, an index.d.ts file located on the root of the repository allows the TypeScript compiler to locate them, no additional configuration is needed to consume the typings.

You may also decide to import a specific module from the library, by doing so, the module types will be automatically imported with it:

import hideModifier from '@popperjs/core/lib/modifiers/hide';