@wordpress/shortcode

Shortcode

Shortcode module for WordPress.

Installation

Install the module

npm install @wordpress/shortcode --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 in your code.

API

attrs

Parse shortcode attributes.

Shortcodes accept many types of attributes. These can chiefly be divided into named and numeric attributes:

Named attributes are assigned on a key/value basis, while numeric attributes are treated as an array.

Named attributes can be formatted as either name="value", name='value', or name=value. Numeric attributes can be formatted as "value" or just value.

Parameters

• text string: Serialised shortcode attributes.

Returns

• ShortcodeAttrs: Parsed shortcode attributes.

default

Creates a shortcode instance.

To access a raw representation of a shortcode, pass an options object, containing a tag string, a string or object of attrs, a string indicating the type of the shortcode ('single', 'self-closing', or 'closed'), and a content string.

Type

• Shortcode

fromMatch

Generate a Shortcode Object from a RegExp match.

Accepts a match object from calling regexp.exec() on a RegExp generated by regexp(). match can also be set to the arguments from a callback passed to regexp.replace().

Parameters

• match Match: Match array.

Returns

• ShortcodeInstance: Shortcode instance.

next

Find the next matching shortcode.

Parameters

• tag string: Shortcode tag.
• text string: Text to search.
• index number: Index to start search from.

Returns

• ShortcodeMatch | undefined: Matched information.

regexp

Generate a RegExp to identify a shortcode.

The base regex is functionally equivalent to the one found in get_shortcode_regex() in wp-includes/shortcodes.php.

Capture groups:

• An extra [ to allow for escaping shortcodes with double [[]]
• The shortcode name
• The shortcode argument list
• The self closing /
• The content of a shortcode when it wraps some content.
• The closing tag.
• An extra ] to allow for escaping shortcodes with double [[]]

Parameters

• tag string: Shortcode tag.

Returns

• RegExp: Shortcode RegExp.

replace

Replace matching shortcodes in a block of text.

Parameters

• tag string: Shortcode tag.
• text string: Text to search.
• callback ReplaceCallback: Function to process the match and return replacement string.

Returns

• Text with shortcodes replaced.

string

Generate a string from shortcode parameters.

Creates a shortcode instance and returns a string.

Accepts the same options as the shortcode() constructor, containing a tag string, a string or object of attrs, a boolean indicating whether to format the shortcode using a single tag, and a content string.

Parameters

• options ShortcodeOptions: Shortcode options.

Returns

• string: String representation of the shortcode.

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 and used by WordPress 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.