# Plugins

Plugins module for WordPress.

## Installation

Install the module

```bash
npm install @wordpress/plugins --save
```

_This package assumes that your code will run in an **ES2015+** environment. If you're using an environment that has limited or no support for such language features and APIs, you should include [the polyfill shipped in `@wordpress/babel-preset-default`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/babel-preset-default#polyfill) in your code._

### Plugins API

<!-- START TOKEN(Autogenerated API docs) -->

#### getPlugin

Returns a registered plugin settings.

_Parameters_

-   _name_ `string`: Plugin name.

_Returns_

-   `WPPlugin | undefined`: Plugin setting.

#### getPlugins

Returns all registered plugins without a scope or for a given scope.

_Parameters_

-   _scope_ `string`: The scope to be used when rendering inside a plugin area. No scope by default.

_Returns_

-   `WPPlugin[]`: The list of plugins without a scope or for a given scope.

#### PluginArea

A component that renders all plugin fills in a hidden div.

_Usage_

```js
// Using ES5 syntax
var el = React.createElement;
var PluginArea = wp.plugins.PluginArea;

function Layout() {
	return el( 'div', { scope: 'my-page' }, 'Content of the page', PluginArea );
}
```

```js
// Using ESNext syntax
import { PluginArea } from '@wordpress/plugins';

const Layout = () => (
	<div>
		Content of the page
		<PluginArea scope="my-page" />
	</div>
);
```

_Parameters_

-   _props_ `{ scope?: string; onError?: ( name: WPPlugin[ 'name' ], error: Error ) => void; }`:
-   _props.scope_ `string`:
-   _props.onError_ `( name: WPPlugin[ 'name' ], error: Error ) => void`:

_Returns_

-   `Component`: The component to be rendered.

#### registerPlugin

Registers a plugin to the editor.

_Usage_

```js
// Using ES5 syntax
var el = React.createElement;
var Fragment = wp.element.Fragment;
var PluginSidebar = wp.editor.PluginSidebar;
var PluginSidebarMoreMenuItem = wp.editor.PluginSidebarMoreMenuItem;
var registerPlugin = wp.plugins.registerPlugin;
var moreIcon = React.createElement( 'svg' ); //... svg element.

function Component() {
	return el(
		Fragment,
		{},
		el(
			PluginSidebarMoreMenuItem,
			{
				target: 'sidebar-name',
			},
			'My Sidebar'
		),
		el(
			PluginSidebar,
			{
				name: 'sidebar-name',
				title: 'My Sidebar',
			},
			'Content of the sidebar'
		)
	);
}
registerPlugin( 'plugin-name', {
	icon: moreIcon,
	render: Component,
	scope: 'my-page',
} );
```

```js
// Using ESNext syntax
import { PluginSidebar, PluginSidebarMoreMenuItem } from '@wordpress/editor';
import { registerPlugin } from '@wordpress/plugins';
import { more } from '@wordpress/icons';

const Component = () => (
	<>
		<PluginSidebarMoreMenuItem target="sidebar-name">
			My Sidebar
		</PluginSidebarMoreMenuItem>
		<PluginSidebar name="sidebar-name" title="My Sidebar">
			Content of the sidebar
		</PluginSidebar>
	</>
);

registerPlugin( 'plugin-name', {
	icon: more,
	render: Component,
	scope: 'my-page',
} );
```

_Parameters_

-   _name_ `string`: A string identifying the plugin. Must be unique across all registered plugins.
-   _settings_ `PluginSettings`: The settings for this plugin.

_Returns_

-   `PluginSettings | null`: The final plugin settings object.

#### unregisterPlugin

Unregisters a plugin by name.

_Usage_

```js
// Using ES5 syntax
var unregisterPlugin = wp.plugins.unregisterPlugin;

unregisterPlugin( 'plugin-name' );
```

```js
// Using ESNext syntax
import { unregisterPlugin } from '@wordpress/plugins';

unregisterPlugin( 'plugin-name' );
```

_Parameters_

-   _name_ `string`: Plugin name.

_Returns_

-   `WPPlugin | undefined`: The previous plugin settings object, if it has been successfully unregistered; otherwise `undefined`.

#### usePluginContext

A hook that returns the plugin context.

_Returns_

-   `PluginContext`: Plugin context

#### withPluginContext

> **Deprecated** 6.8.0 Use `usePluginContext` hook instead.

A Higher Order Component used to inject Plugin context to the wrapped component.

_Parameters_

-   _mapContextToProps_ `( context: PluginContext, props: T ) => T & PluginContext`: Function called on every context change, expected to return object of props to merge with the component's own props.

_Returns_

-   `Component`: Enhanced component with injected context as props.

<!-- END TOKEN(Autogenerated API docs) -->

## Contributing to this package

This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects.

To find out more about contributing to this package or Gutenberg as a whole, please read the project's main [contributor guide](https://github.com/WordPress/gutenberg/tree/HEAD/CONTRIBUTING.md).

<br /><br /><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>