README.md

URLInputButton

Render a URL input button that pops up an input to search for and select a post or enter any arbitrary URL.

Properties

url: String

Required. This should be set to the attribute (or component state) property used to store the URL.

onChange( url: String, ?post: Object ): Function

Required. Called when the value changes. The second parameter is null unless the user selects a post from the suggestions dropdown. In those cases the post parameter will look like this:

{
	"id": 1,
	"subtype": "page",
	"title": "Sample Page",
	"type": "post",
	"url": "https://example.com/sample-page/",
	"_links": {
		"self": [
			{
				"embeddable": true,
				"href": "https://example.com/wp-json/wp/v2/pages/1"
			}
		],
		"about": [ { "href": "https://example.com/wp-json/wp/v2/types/page" } ],
		"collection": [ { "href": "https://example.com/wp-json/wp/v2/search" } ]
	}
}

This prop is passed directly to the URLInput component.

Example

import { registerBlockType } from '@wordpress/blocks';
import { URLInputButton } from '@wordpress/block-editor';

registerBlockType( /* ... */, {
	// ...

	attributes: {
		url: {
			type: 'string',
		},
		text: {
			type: 'string',
		},
	},

	edit( { className, attributes, setAttributes } ) {
		return (
			<URLInputButton
				url={ attributes.url }
				onChange={ ( url, post ) => setAttributes( { url, text: (post && post.title) || 'Click here' } ) }
			/>
		);
	},

	save( { attributes } ) {
		return <a href={ attributes.url }>{ attributes.text }</a>;
	}
} );

URLInput

Renders the URL input field used by the URLInputButton component. It can be used directly to display the input field in different ways such as in a Popover or inline.

Properties

value: String

Required. This should be set to the attribute (or component state) property used to store the URL.

onChange( url: String, ?post: Object ): Function

Required. Called when the value changes. The second parameter is null unless the user selects a post from the suggestions dropdown. In those cases the post parameter will look like this:

{
	"id": 1,
	"subtype": "page",
	"title": "Sample Page",
	"type": "post",
	"url": "https://example.com/sample-page/",
	"_links": {
		"self": [
			{
				"embeddable": true,
				"href": "https://example.com/wp-json/wp/v2/pages/1"
			}
		],
		"about": [ { "href": "https://example.com/wp-json/wp/v2/types/page" } ],
		"collection": [ { "href": "https://example.com/wp-json/wp/v2/search" } ]
	}
}

onKeyDown: ( event: KeyboardEvent ) => void

A callback invoked on the keydown event.

• Required: No

label: String

Optional. If this property is added, a label will be generated using label property as the content.

className: String

Optional. Adds and optional class to the parent div that wraps the URLInput field and popover

placeholder: String

Optional. Placeholder text to show when the field is empty, similar to the input and textarea attribute of the same name.

disableSuggestions: Boolean

Optional. Provides additional control over whether suggestions are disabled.

When hiding the URLInput using CSS (as is sometimes done for accessibility purposes), the suggestions can still be displayed. This is because they're rendered in a popover in a different part of the DOM, so any styles applied to the URLInput's container won't affect the popover.

This prop allows the suggestions list to be programmatically not rendered by passing a boolean—it can be true to make sure suggestions aren't rendered, or false/undefined to fall back to the default behaviour of showing suggestions when matching autocompletion items are found.

__nextHasNoMarginBottom: Boolean

Start opting into the new margin-free styles that will become the default in a future version, currently scheduled to be WordPress 6.4. (The prop can be safely removed once this happens.)

Example

import { registerBlockType } from '@wordpress/blocks';
import { URLInput } from '@wordpress/block-editor';

registerBlockType( /* ... */, {
	// ...

	attributes: {
		url: {
			type: 'string',
		},
		text: {
			type: 'string',
		},
	},

	edit( { className, attributes, setAttributes } ) {
		return (
			<URLInput
				__nextHasNoMarginBottom
				className={ className }
				value={ attributes.url }
				onChange={ ( url, post ) => setAttributes( { url, text: (post && post.title) || 'Click here' } ) }
			/>
		);
	},

	save( { attributes } ) {
		return <a href={ attributes.url }>{ attributes.text }</a>;
	}
} );