# Block Editor

This module allows you to create and use standalone block editors.

## Installation

Install the module

```bash
npm install @wordpress/block-editor --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._

## Usage

```js
import { useState } from 'react';
import {
	BlockCanvas,
	BlockEditorProvider,
	BlockList,
} from '@wordpress/block-editor';

function MyEditorComponent() {
	const [ blocks, updateBlocks ] = useState( [] );

	return (
		<BlockEditorProvider
			value={ blocks }
			onInput={ ( blocks ) => updateBlocks( blocks ) }
			onChange={ ( blocks ) => updateBlocks( blocks ) }
		>
			<BlockCanvas height="400px" />
		</BlockEditorProvider>
	);
}

// Make sure to load the block editor stylesheets too
// import '@wordpress/components/build-style/style.css';
// import '@wordpress/block-editor/build-style/style.css';
```

In this example, we're instantiating a block editor. A block editor is composed by a `BlockEditorProvider` wrapper component where you pass the current array of blocks and on each change the `onInput` or `onChange` callbacks are called depending on whether the change is considered persistent or not.

Inside `BlockEditorProvider`, you can nest any of the available `@wordpress/block-editor` UI components to build the UI of your editor.

In the example above we're rendering the `BlockList` to show and edit the block list. For instance we could add a custom sidebar and use the `BlockInspector` component to be able to edit the advanced settings for the currently selected block. (See the [API](#api) for the list of all the available components).

The `BlockTools` component is used to render the toolbar for a selected block.

In the example above, there's no registered block type, in order to use the block editor successfully make sure to register some block types. For instance, registering the core block types can be done like so:

```js
import { registerCoreBlocks } from '@wordpress/block-library';

registerCoreBlocks();

// Make sure to load the block stylesheets too
// import '@wordpress/block-library/build-style/style.css';
// import '@wordpress/block-library/build-style/editor.css';
// import '@wordpress/block-library/build-style/theme.css';
```

## API

Any components in this package that have a counterpart in [@wordpress/components](/packages/components/README.md) are an extension of those components.

Unless you're [creating an editor](/docs/how-to-guides/platform/custom-block-editor.md), it is recommended that the components in @wordpress/components should be used rather than the ones in this package as these components have been customized for use in an editor and may result in unexpected behaviour if used outside of this context.

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

### AlignmentControl

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/alignment-control/README.md>

### AlignmentToolbar

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/alignment-control/README.md>

### Autocomplete

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/autocomplete/README.md>

### BlockAlignmentControl

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-alignment-control/README.md>

### BlockAlignmentToolbar

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-alignment-control/README.md>

### BlockBindingsAttributeControl

Internal dependencies

### BlockBindingsSourceFieldsList

Undocumented declaration.

### BlockBreadcrumb

Block breadcrumb component, displaying the hierarchy of the current block selection as a breadcrumb.

_Parameters_

-   _props_ `Object`: Component props.
-   _props.rootLabelText_ `string`: Translated label for the root element of the breadcrumb trail.

_Returns_

-   `Element`: Block Breadcrumb.

### BlockCanvas

BlockCanvas component is a component used to display the canvas of the block editor. What we call the canvas is an iframe containing the block list that you can manipulate. The component is also responsible of wiring up all the necessary hooks to enable the keyboard navigation across blocks in the editor and inject content styles into the iframe.

_Usage_

```jsx
function MyBlockEditor() {
	const [ blocks, updateBlocks ] = useState( [] );
	return (
		<BlockEditorProvider
			value={ blocks }
			onInput={ updateBlocks }
			onChange={ persistBlocks }
		>
			<BlockCanvas height="400px" />
		</BlockEditorProvider>
	);
}
```

_Parameters_

-   _props_ `Object`: Component props.
-   _props.height_ `string`: Canvas height, defaults to 300px.
-   _props.styles_ `Array`: Content styles to inject into the iframe.
-   _props.children_ `Element`: Content of the canvas, defaults to the BlockList component.

_Returns_

-   `Element`: Block Breadcrumb.

### BlockColorsStyleSelector

Undocumented declaration.

### BlockContextProvider

Component which merges passed value with current consumed block context.

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-context/README.md>

_Parameters_

-   _props_ `BlockContextProviderProps`:

### BlockControls

Undocumented declaration.

### BlockEdit

Undocumented declaration.

### BlockEditorKeyboardShortcuts

Undocumented declaration.

### BlockEditorProvider

Undocumented declaration.

### BlockFormatControls

Undocumented declaration.

### BlockIcon

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-icon/README.md>

### BlockInspector

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-inspector/README.md>

### BlockList

Undocumented declaration.

### BlockMover

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-mover/README.md>

### BlockNavigationDropdown

Undocumented declaration.

### BlockPopover

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-popover/README.md>

### BlockPreview

BlockPreview renders a preview of a block or array of blocks.

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-preview/README.md>

_Parameters_

-   _preview_ `Object`: options for how the preview should be shown
-   _preview.blocks_ `Array|Object`: A block instance (object) or an array of blocks to be previewed.
-   _preview.viewportWidth_ `number`: Width of the preview container in pixels. Controls at what size the blocks will be rendered inside the preview. Default: 700.

_Returns_

-   `Component`: The component to be rendered.

### BlockSelectionClearer

Undocumented declaration.

### BlockSettingsMenu

Undocumented declaration.

### BlockSettingsMenuControls

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-settings-menu-controls/README.md>

_Parameters_

-   _props_ `Object`: Fill props.

_Returns_

-   `Element`: Element.

### BlockStyles

Undocumented declaration.

### BlockTitle

Renders the block's configured title as a string, or empty if the title cannot be determined.

_Usage_

```jsx
<BlockTitle
	clientId="afd1cb17-2c08-4e7a-91be-007ba7ddc3a1"
	maximumLength={ 17 }
/>
```

_Parameters_

-   _props_ `Object`:
-   _props.clientId_ `string`: Client ID of block.
-   _props.maximumLength_ `number|undefined`: The maximum length that the block title string may be before truncated.
-   _props.context_ `string|undefined`: The context to pass to `getBlockLabel`.

_Returns_

-   `JSX.Element`: Block title.

### BlockToolbar

Renders the block toolbar.

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-toolbar/README.md>

_Parameters_

-   _props_ `Object`: Components props.
-   _props.hideDragHandle_ `boolean`: Show or hide the Drag Handle for drag and drop functionality.
-   _props.variant_ `string`: Style variant of the toolbar, also passed to the Dropdowns rendered from Block Toolbar Buttons.

### BlockTools

Renders block tools (the block toolbar, select/navigation mode toolbar, the insertion point and a slot for the inline rich text toolbar). Must be wrapped around the block content and editor styles wrapper or iframe.

_Parameters_

-   _$0_ `Object`: Props.
-   _$0.children_ `Object`: The block content and style container.
-   _$0.\_\_unstableContentRef_ `Object`: Ref holding the content scroll container.

### BlockVerticalAlignmentControl

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-vertical-alignment-control/README.md>

### BlockVerticalAlignmentToolbar

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-vertical-alignment-control/README.md>

### ButtonBlockAppender

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/button-block-appender/README.md>

### ButtonBlockerAppender

> **Deprecated**

Use `ButtonBlockAppender` instead.

### ColorPalette

Undocumented declaration.

### ColorPaletteControl

Undocumented declaration.

### ContrastChecker

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/contrast-checker/README.md>

### CopyHandler

> **Deprecated**

_Parameters_

-   _props_ `Object`:

### createCustomColorsHOC

A higher-order component factory for creating a 'withCustomColors' HOC, which handles color logic for class generation color value, retrieval and color attribute setting.

Use this higher-order component to work with a custom set of colors.

_Usage_

```jsx
const CUSTOM_COLORS = [
	{ name: 'Red', slug: 'red', color: '#ff0000' },
	{ name: 'Blue', slug: 'blue', color: '#0000ff' },
];
const withCustomColors = createCustomColorsHOC( CUSTOM_COLORS );
// ...
export default compose(
	withCustomColors( 'backgroundColor', 'borderColor' ),
	MyColorfulComponent
);
```

_Parameters_

-   _colorsArray_ `Array`: The array of color objects (name, slug, color, etc... ).

_Returns_

-   `Function`: Higher-order component.

### DefaultBlockAppender

Undocumented declaration.

### DimensionControl

DimensionControl renders a linked unit control and range control for adjusting dimensions of a block.

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/dimension-control/README.md>

_Parameters_

-   _props_ `Object`:
-   _props.label_ `?string`: A label for the control.
-   _props.onChange_ `( value: string ) => void`: Called when the dimension value changes.
-   _props.value_ `string`: The current dimension value.

_Returns_

-   `Component`: The component to be rendered.

### FontSizePicker

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/font-sizes/README.md>

### getColorClassName

Returns a class based on the context a color is being used and its slug.

_Parameters_

-   _colorContextName_ `string`: Context/place where color is being used e.g: background, text etc...
-   _colorSlug_ `string`: Slug of the color.

_Returns_

-   `?string`: String with the class corresponding to the color in the provided context. Returns undefined if either colorContextName or colorSlug are not provided.

### getColorObjectByAttributeValues

Provided an array of color objects as set by the theme or by the editor defaults, and the values of the defined color or custom color returns a color object describing the color.

_Parameters_

-   _colors_ `Array`: Array of color objects as set by the theme or by the editor defaults.
-   _definedColor_ `?string`: A string containing the color slug.
-   _customColor_ `?string`: A string containing the customColor value.

_Returns_

-   `?Object`: If definedColor is passed and the name is found in colors, the color object exactly as set by the theme or editor defaults is returned. Otherwise, an object that just sets the color is defined.

### getColorObjectByColorValue

Provided an array of color objects as set by the theme or by the editor defaults, and a color value returns the color object matching that value or undefined.

_Parameters_

-   _colors_ `Array`: Array of color objects as set by the theme or by the editor defaults.
-   _colorValue_ `?string`: A string containing the color value.

_Returns_

-   `?Object`: Color object included in the colors array whose color property equals colorValue. Returns undefined if no color object matches this requirement.

### getComputedFluidTypographyValue

Computes a fluid font-size value that uses clamp(). A minimum and maximum font size OR a single font size can be specified.

If a single font size is specified, it is scaled up and down using a logarithmic scale.

_Usage_

```js
// Calculate fluid font-size value from a minimum and maximum value.
const fontSize = getComputedFluidTypographyValue( {
	minimumFontSize: '20px',
	maximumFontSize: '45px',
} );
// Calculate fluid font-size value from a single font size.
const fontSize = getComputedFluidTypographyValue( {
	fontSize: '30px',
} );
```

_Parameters_

-   _args_ `Object`:
-   _args.minimumViewportWidth_ `?string`: Minimum viewport size from which type will have fluidity. Optional if fontSize is specified.
-   _args.maximumViewportWidth_ `?string`: Maximum size up to which type will have fluidity. Optional if fontSize is specified.
-   _args.fontSize_ `[string|number]`: Size to derive maximumFontSize and minimumFontSize from, if necessary. Optional if minimumFontSize and maximumFontSize are specified.
-   _args.maximumFontSize_ `?string`: Maximum font size for any clamp() calculation. Optional.
-   _args.minimumFontSize_ `?string`: Minimum font size for any clamp() calculation. Optional.
-   _args.scaleFactor_ `?number`: A scale factor to determine how fast a font scales within boundaries. Optional.
-   _args.minimumFontSizeLimit_ `?string`: The smallest a calculated font size may be. Optional.

_Returns_

-   `string|null`: A font-size value using clamp().

### getCustomValueFromPreset

Converts a spacing preset into a custom value.

_Parameters_

-   _value_ `string`: Value to convert
-   _spacingSizes_ `Array`: Array of the current spacing preset objects

_Returns_

-   `string`: Mapping of the spacing preset to its equivalent custom value.

### getFontSize

Returns the font size object based on an array of named font sizes and the namedFontSize and customFontSize values. If namedFontSize is undefined or not found in fontSizes an object with just the size value based on customFontSize is returned.

_Parameters_

-   _fontSizes_ `Array`: Array of font size objects containing at least the "name" and "size" values as properties.
-   _fontSizeAttribute_ `?string`: Content of the font size attribute (slug).
-   _customFontSizeAttribute_ `?number`: Contents of the custom font size attribute (value).

_Returns_

-   `?Object`: If fontSizeAttribute is set and an equal slug is found in fontSizes it returns the font size object for that slug. Otherwise, an object with just the size value based on customFontSize is returned.

### getFontSizeClass

Returns a class based on fontSizeName.

_Parameters_

-   _fontSizeSlug_ `string`: Slug of the fontSize.

_Returns_

-   `string | undefined`: String with the class corresponding to the fontSize passed. The class is generated by appending 'has-' followed by fontSizeSlug in kebabCase and ending with '-font-size'.

### getFontSizeObjectByValue

Returns the corresponding font size object for a given value.

_Parameters_

-   _fontSizes_ `Array`: Array of font size objects.
-   _value_ `number`: Font size value.

_Returns_

-   `Object`: Font size object.

### getGradientSlugByValue

Retrieves the gradient slug per slug.

_Parameters_

-   _gradients_ `Array`: Gradient Palette
-   _value_ `string`: Gradient value

_Returns_

-   `string`: Gradient slug.

### getGradientValueBySlug

Retrieves the gradient value per slug.

_Parameters_

-   _gradients_ `Array`: Gradient Palette
-   _slug_ `string`: Gradient slug

_Returns_

-   `string`: Gradient value.

### getPxFromCssUnit

> **Deprecated**

This function was accidentally exposed for mobile/native usage.

_Returns_

-   `string`: Empty string.

### getSpacingPresetCssVar

Converts a spacing preset into a custom value.

_Parameters_

-   _value_ `string`: Value to convert.

_Returns_

-   `string | undefined`: CSS var string for given spacing preset value.

### getTypographyClassesAndStyles

Provides the CSS class names and inline styles for a block's typography support attributes.

_Parameters_

-   _attributes_ `Object`: Block attributes.
-   _settings_ `Object|boolean`: Merged theme.json settings

_Returns_

-   `Object`: Typography block support derived CSS classes & styles.

### HeadingLevelDropdown

Dropdown for selecting a heading level (1 through 6) or paragraph (0).

_Parameters_

-   _props_ `WPHeadingLevelDropdownProps`: Component props.

_Returns_

-   `ComponentType`: The toolbar.

### HeightControl

> **Deprecated** Use DimensionControl instead.

HeightControl renders a linked unit control and range control for adjusting the height of a block.

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/height-control/README.md>

_Parameters_

-   _props_ `Object`:
-   _props.label_ `?string`: A label for the control.
-   _props.onChange_ `( value: string ) => void`: Called when the height changes.
-   _props.value_ `string`: The current height value.

_Returns_

-   `Component`: The component to be rendered.

### InnerBlocks

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inner-blocks/README.md>

### Inserter

Undocumented declaration.

### InspectorAdvancedControls

Undocumented declaration.

### InspectorControls

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inspector-controls/README.md>

### isValueSpacingPreset

Checks is given value is a spacing preset.

_Parameters_

-   _value_ `string`: Value to check

_Returns_

-   `boolean`: Return true if value is string in format var:preset|spacing|.

### JustifyContentControl

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/justify-content-control/README.md>

### JustifyToolbar

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/justify-content-control/README.md>

### LineHeightControl

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/line-height-control/README.md>

### LinkControl

Renders a link control. A link control is a controlled input which maintains a value associated with a link (HTML anchor element) and relevant settings for how that link is expected to behave.

_Parameters_

-   _props_ `WPLinkControlProps`: Component props.

### MediaPlaceholder

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/media-placeholder/README.md>

### MediaReplaceFlow

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/media-replace-flow/README.md>

### MediaUpload

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/media-upload/README.md>

### MediaUploadCheck

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/media-upload/README.md>

### MultiSelectScrollIntoView

> **Deprecated**

Scrolls the multi block selection end into view if not in view already. This is important to do after selection by keyboard.

### NavigableToolbar

Undocumented declaration.

### ObserveTyping

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/observe-typing/README.md>

### PanelColorSettings

Undocumented declaration.

### PlainText

Render an auto-growing textarea allow users to fill any textual content.

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/plain-text/README.md>

_Usage_

```jsx
import { registerBlockType } from '@wordpress/blocks';
import { PlainText } from '@wordpress/block-editor';

registerBlockType( 'my-plugin/example-block', {
	// ...

	attributes: {
		content: {
			type: 'string',
		},
	},

	edit( { className, attributes, setAttributes } ) {
		return (
			<PlainText
				className={ className }
				value={ attributes.content }
				onChange={ ( content ) => setAttributes( { content } ) }
			/>
		);
	},
} );
```

_Parameters_

-   _props_ `Object`: Component props.
-   _props.value_ `string`: String value of the textarea.
-   _props.onChange_ `Function`: Function called when the text value changes.
-   _props.ref_ `[Object]`: The component forwards the `ref` property to the `TextareaAutosize` component.

_Returns_

-   `Element`: Plain text component

### privateApis

Private @wordpress/block-editor APIs.

### RecursionProvider

A React context provider for use with the `useHasRecursion` hook to prevent recursive renders.

Wrap block content with this provider and provide the same `uniqueId` prop as used with `useHasRecursion`.

_Parameters_

-   _props_ `Object`:
-   _props.uniqueId_ `*`: Any value that acts as a unique identifier for a block instance.
-   _props.blockName_ `string`: Optional block name.
-   _props.children_ `JSX.Element`: React children.

_Returns_

-   `JSX.Element`: A React element.

### RichText

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/rich-text/README.md>

### RichTextShortcut

Undocumented declaration.

### RichTextToolbarButton

Undocumented declaration.

### SETTINGS_DEFAULTS

The default editor settings

_Type Definition_

-   _SETTINGS_DEFAULT_ `Object`

_Properties_

-   _alignWide_ `boolean`: Enable/Disable Wide/Full Alignments
-   _supportsLayout_ `boolean`: Enable/disable layouts support in container blocks.
-   _imageEditing_ `boolean`: Image Editing settings set to false to disable.
-   _imageSizes_ `Array`: Available image sizes
-   _maxWidth_ `number`: Max width to constraint resizing
-   _allowedBlockTypes_ `boolean|Array`: Allowed block types
-   _hasFixedToolbar_ `boolean`: Whether or not the editor toolbar is fixed
-   _distractionFree_ `boolean`: Whether or not the editor UI is distraction free
-   _focusMode_ `boolean`: Whether the focus mode is enabled or not
-   _styles_ `Array`: Editor Styles
-   _keepCaretInsideBlock_ `boolean`: Whether caret should move between blocks in edit mode
-   _bodyPlaceholder_ `string`: Empty post placeholder
-   _titlePlaceholder_ `string`: Empty title placeholder
-   _canLockBlocks_ `boolean`: Whether the user can manage Block Lock state
-   _codeEditingEnabled_ `boolean`: Whether or not the user can switch to the code editor
-   _generateAnchors_ `boolean`: Enable/Disable auto anchor generation for Heading blocks
-   _enableOpenverseMediaCategory_ `boolean`: Enable/Disable the Openverse media category in the inserter.
-   _clearBlockSelection_ `boolean`: Whether the block editor should clear selection on mousedown when a block is not clicked.
-   _\_\_experimentalCanUserUseUnfilteredHTML_ `boolean`: Whether the user should be able to use unfiltered HTML or the HTML should be filtered e.g., to remove elements considered insecure like iframes.
-   _\_\_experimentalBlockDirectory_ `boolean`: Whether the user has enabled the Block Directory
-   _\_\_experimentalBlockPatterns_ `Array`: Array of objects representing the block patterns
-   _\_\_experimentalBlockPatternCategories_ `Array`: Array of objects representing the block pattern categories

### SkipToSelectedBlock

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/skip-to-selected-block/README.md>

### store

Store definition for the block editor namespace.

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/data/README.md#createReduxStore>

### storeConfig

Block editor data store configuration.

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/data/README.md#registerStore>

### ToolSelector

This component has been deprecated and no longer renders anything.

### transformStyles

Applies a series of CSS rule transforms to wrap selectors inside a given class and/or rewrite URLs depending on the parameters passed.

_Parameters_

-   _styles_ `EditorStyle[]`: CSS rules.
-   _wrapperSelector_ `string`: Wrapper selector.
-   _transformOptions_ `TransformOptions`: Additional options for style transformation.

_Returns_

-   `Array`: converted rules.

### Typewriter

Ensures that the text selection keeps the same vertical distance from the viewport during keyboard events within this component. The vertical distance can vary. It is the last clicked or scrolled to position.

### URLInput

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/url-input/README.md>

### URLInputButton

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/url-input/README.md>

### URLPopover

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/url-popover/README.md>

### useBlockBindingsUtils

Retrieves the existing utils needed to update the block `bindings` metadata. They can be used to create, modify, or remove connections from the existing block attributes.

It contains the following utils:

-   `updateBlockBindings`: Updates the value of the bindings connected to block attributes. It can be used to remove a specific binding by setting the value to `undefined`.
-   `removeAllBlockBindings`: Removes the bindings property of the `metadata` attribute.

_Usage_

```js
import { useBlockBindingsUtils } from '@wordpress/block-editor';
const { updateBlockBindings, removeAllBlockBindings } = useBlockBindingsUtils();

// Update url and alt attributes.
updateBlockBindings( {
	url: {
		source: 'core/post-meta',
		args: {
			key: 'url_custom_field',
		},
	},
	alt: {
		source: 'core/post-meta',
		args: {
			key: 'text_custom_field',
		},
	},
} );

// Remove binding from url attribute.
updateBlockBindings( { url: undefined } );

// Remove bindings from all attributes.
removeAllBlockBindings();
```

_Parameters_

-   _clientId_ `?string`: Optional block client ID. If not set, it will use the current block client ID from the context.

_Returns_

-   `?WPBlockBindingsUtils`: Object containing the block bindings utils.

_Changelog_

`6.7.0` Introduced in WordPress core.

### useBlockCommands

Undocumented declaration.

### useBlockDisplayInformation

Hook used to try to find a matching block variation and return the appropriate information for display reasons. In order to to try to find a match we need to things: 1. Block's client id to extract it's current attributes. 2. A block variation should have set `isActive` prop to a proper function.

If for any reason a block variation match cannot be found, the returned information come from the Block Type. If no blockType is found with the provided clientId, returns null.

_Parameters_

-   _clientId_ `string`: Block's client id.

_Returns_

-   `?WPBlockDisplayInformation`: Block's display information, or `null` when the block or its type not found.

### useBlockEditContext

The `useBlockEditContext` hook provides information about the block this hook is being used in. It returns an object with the `name`, `isSelected` state, and the `clientId` of the block. It is useful if you want to create custom hooks that need access to the current blocks clientId but don't want to rely on the data getting passed in as a parameter.

_Returns_

-   `Object`: Block edit context

### useBlockEditingMode

Allows a block to restrict the user interface that is displayed for editing that block and its inner blocks.

_Usage_

```js
function MyBlock( { attributes, setAttributes } ) {
	useBlockEditingMode( 'disabled' );
	return <div { ...useBlockProps() }></div>;
}
```

`mode` can be one of three options:

-   `'disabled'`: Prevents editing the block entirely, i.e. it cannot be
    selected.
-   `'contentOnly'`: Hides all non-content UI, e.g. auxiliary controls in the
    toolbar, the block movers, block settings.
-   `'default'`: Allows editing the block as normal.

The mode is inherited by all of the block's inner blocks, unless they have
their own mode.

If called outside of a block context, the mode is applied to all blocks.

_Parameters_

-   _mode_ `?BlockEditingMode`: The editing mode to apply. If undefined, the current editing mode is not changed.

_Returns_

-   `BlockEditingMode`: The current editing mode.

### useBlockProps

This hook is used to lightly mark an element as a block element. The element should be the outermost element of a block. Call this hook and pass the returned props to the element to mark as a block. If you define a ref for the element, it is important to pass the ref to this hook, which the hook in turn will pass to the component through the props it returns. Optionally, you can also pass any other props through this hook, and they will be merged and returned.

Use of this hook on the outermost element of a block is required if using API >= v2.

_Usage_

```js
import { useBlockProps } from '@wordpress/block-editor';

export default function Edit() {
	const blockProps = useBlockProps( {
		className: 'my-custom-class',
		style: {
			color: '#222222',
			backgroundColor: '#eeeeee',
		},
	} );

	return <div { ...blockProps }></div>;
}
```

_Parameters_

-   _props_ `Object`: Optional. Props to pass to the element. Must contain the ref if one is defined.
-   _options_ `Object`: Options for internal use only.
-   _options.\_\_unstableIsHtml_ `boolean`:

_Returns_

-   `Object`: Props to pass to the element to mark as a block.

### useCachedTruthy

Keeps an up-to-date copy of the passed value and returns it. If value becomes falsy, it will return the last truthy copy.

_Parameters_

-   _value_ `any`:

_Returns_

-   `any`: value

### useHasRecursion

A React hook for keeping track of blocks previously rendered up in the block tree. Blocks susceptible to recursion can use this hook in their `Edit` function to prevent said recursion.

Use this with the `RecursionProvider` component, using the same `uniqueId` value for both the hook and the provider.

_Parameters_

-   _uniqueId_ `*`: Any value that acts as a unique identifier for a block instance.
-   _blockName_ `string`: Optional block name.

_Returns_

-   `boolean`: A boolean describing whether the provided id has already been rendered.

### useInnerBlocksProps

This hook is used to lightly mark an element as an inner blocks wrapper element. Call this hook and pass the returned props to the element to mark as an inner blocks wrapper, automatically rendering inner blocks as children. If you define a ref for the element, it is important to pass the ref to this hook, which the hook in turn will pass to the component through the props it returns. Optionally, you can also pass any other props through this hook, and they will be merged and returned.

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inner-blocks/README.md>

_Parameters_

-   _props_ `Object`: Optional. Props to pass to the element. Must contain the ref if one is defined.
-   _options_ `Object`: Optional. Inner blocks options.

### useSetting

> **Deprecated** 6.5.0 Use useSettings instead.

Hook that retrieves the given setting for the block instance in use.

It looks up the setting first in the block instance hierarchy. If none is found, it'll look it up in the block editor settings.

_Usage_

```js
const isEnabled = useSetting( 'typography.dropCap' );
```

_Parameters_

-   _path_ `string`: The path to the setting.

_Returns_

-   `any`: Returns the value defined for the setting.

### useSettings

Hook that retrieves the given settings for the block instance in use.

It looks up the settings first in the block instance hierarchy. If none are found, it'll look them up in the block editor settings.

_Usage_

```js
const [ fixed, sticky ] = useSettings( 'position.fixed', 'position.sticky' );
```

_Parameters_

-   _paths_ `string[]`: The paths to the settings.

_Returns_

-   `any[]`: Returns the values defined for the settings.

### useStyleOverride

Override a block editor settings style. Leave the ID blank to create a new style.

_Parameters_

-   _override_ `Object`: Override object.
-   _override.id_ `?string`: Id of the style override, leave blank to create a new style.
-   _override.css_ `string`: CSS to apply.

### Warning

_Related_

-   <https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/warning/README.md>

### withColorContext

Undocumented declaration.

### withColors

A higher-order component, which handles color logic for class generation color value, retrieval and color attribute setting.

For use with the default editor/theme color palette.

_Usage_

```jsx
export default compose(
	withColors( 'backgroundColor', { textColor: 'color' } ),
	MyColorfulComponent
);
```

_Parameters_

-   _colorTypes_ `...(Object|string)`: The arguments can be strings or objects. If the argument is an object, it should contain the color attribute name as key and the color context as value. If the argument is a string the value should be the color attribute name, the color context is computed by applying a kebab case transform to the value. Color context represents the context/place where the color is going to be used. The class name of the color is generated using 'has' followed by the color name and ending with the color context all in kebab case e.g: has-green-background-color.

_Returns_

-   `Function`: Higher-order component.

### withFontSizes

Higher-order component, which handles font size logic for class generation, font size value retrieval, and font size change handling.

_Parameters_

-   _fontSizeNames_ `...(Object|string)`: The arguments should all be strings. Each string contains the font size attribute name e.g: 'fontSize'.

_Returns_

-   `Function`: Higher-order component.

### WritingFlow

Handles selection and navigation across blocks. This component should be wrapped around BlockList.

_Parameters_

-   _props_ `Object`: Component properties.
-   _props.children_ `Element`: Children to be rendered.

<!-- 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>
