---
navigationLabel: Constructors
order: 2
---

# Constructors

Popper comes with two constructor functions to use.

<x-ad />

## createPopper

The `createPopper` constructor is at the heart of Popper. It allows you to
create individual popper instances (objects) with state and methods.

### Imports

```js
// esm
import { createPopper } from '@popperjs/core';

// cjs
const { createPopper } = require('@popperjs/core');

// umd
const { createPopper } = Popper;
```

### Usage

```js
const reference = document.querySelector('#reference');
const popper = document.querySelector('#popper');

createPopper(reference, popper, {
  // options
});
```

### Options

```flow
type Options = {|
  placement: Placement, // "bottom"
  modifiers: Array<$Shape<Modifier<any>>>, // []
  strategy: PositioningStrategy, // "absolute",
  onFirstUpdate?: ($Shape<State>) => void, // undefined
|};

type Placement =
  | 'auto'
  | 'auto-start'
  | 'auto-end'
  | 'top'
  | 'top-start'
  | 'top-end'
  | 'bottom'
  | 'bottom-start'
  | 'bottom-end'
  | 'right'
  | 'right-start'
  | 'right-end'
  | 'left'
  | 'left-start'
  | 'left-end';
type Strategy = 'absolute' | 'fixed';
```

### `placement`

Describes the preferred placement of the popper. Modifiers like `flip` may
change the placement of the popper to make it fit better.

```js
createPopper(reference, popper, {
  placement: 'right-start',
});
```

The `"auto"` placements will choose the side with most space.

### `modifiers`

Describes the array of modifiers to add or configure. The default (full) version
of Popper includes all modifiers listed in the menu.

```js
createPopper(reference, popper, {
  modifiers: [
    {
      name: 'flip',
      enabled: false,
    },
  ],
});
```

See [Modifiers](../modifiers/) for more information.

### `strategy`

Describes the positioning strategy to use. By default, it is `absolute`, which
in the simplest cases does not require repositioning of the popper.

If your reference element is in a fixed container, use the `fixed` strategy:

```js
createPopper(reference, popper, {
  strategy: 'fixed',
});
```

This will prevent any jumpiness since no repositioning is needed.

### Instance

`createPopper` returns a popper instance. This is a plain object with a `state`
property and some methods.

Log it out in DevTools:

```js
const instance = createPopper(reference, popper);
console.log(instance);
```

```js
{
  // This is the main state object containing all of the information about the
  // popper.
  state,

  // Synchronously updates the popper instance. Use this for low-frequency
  // updates.
  forceUpdate() {},

  // Asynchronously updates the popper instance, and returns a promise. Use this
  // for high-frequency updates.
  update() {},

  // Updates the options of the instance.
  setOptions(options) {},

  // Cleans up the instance.
  destroy() {},
};
```

### Types

```flow
type CreatePopper = (
  reference: Element | VirtualElement,
  popper: HTMLElement,
  options?: Options
) => Instance;

type Options = {|
  placement: Placement,
  modifiers: Array<$Shape<Modifier<any>>>,
  strategy: PositioningStrategy,
  onFirstUpdate?: ($Shape<State>) => void,
|};

type Instance = {|
  state: State,
  destroy: () => void,
  forceUpdate: () => void,
  update: () => Promise<$Shape<State>>,
  setOptions: (options: $Shape<Options>) => Promise<$Shape<State>>,
|};
```

## popperGenerator

The `popperGenerator` constructor generates a `createPopper` function. This
allows you to configure `createPopper` with the functionality you need instead
of needing to pass the same defaults each time.

### Imports

```js
// esm
import { popperGenerator } from '@popperjs/core';

// cjs
const { popperGenerator } = require('@popperjs/core');

// umd
const { popperGenerator } = Popper;
```

### Usage

```js
const createPopper = popperGenerator({
  defaultOptions: { placement: 'top' },
  defaultModifiers: [popperOffsets, computeStyles, applyStyles, eventListeners],
});

// Now your custom `createPopper` is ready to use.
```

### Types

```flow
type PopperGenerator = (options?: PopperGeneratorOptions) => CreatePopper;

type PopperGeneratorOptions = {
  defaultModifiers?: Array<Modifier<any>>,
  defaultOptions?: $Shape<Options>,
};
```
