LifterLMS UI Components

UI components for use in LifterLMS and LifterLMS add-ons. This package extends functionality provided by @wordpress/components, adding additional components specific to the LifterLMS project.

Usage in a LifterLMS add-on

This package is included in the LifterLMS core plugin as a module and registered using the WordPress scripts dependency API (see [wp_register_script()][https://developer.wordpress.org/reference/functions/wp_register_script/]).

To use components you can add llms-components as a dependency to your script and access the module via window.llms.components, for example:

const { ButtonGroupControl } = window.llms.components;

LifterLMS Versions

The following table records the module version and which LifterLMS versions it has been included in.

| Module Version | LifterLMS Version | | -------------- | ----------------- | | 1.0.0 | 6.0.0 |

Installation

Install the module as a dependency in your project:

npm install --save-dev @lifterlms/components`

Changelog

View the Changelog

API Docs

BaseSearchControl

Searchable element powered by a WordPress REST API endpoint.

Parameters

• args Object: Component arguments.
• args.searchPath string: Required. API path used to perform the search.
• args.onUpdate Function: Callback function invoked when the value of the select changes. The callback function is passed a single parameter, the new selected value object(s). For multiselects it will be an array of objects. If the select is clearable, the value will be null when the select is cleared.
• args.selectedValue Array: The currently selected value(s). If an object is passed, it should contain at least a label and value key. Can pass IDs as integers and the values will be automatically hydrated.
• args.placeholder string: The placeholder displayed within an empty search control.
• args.className string: HTML class attribute added to the select control.
• args.classNamePrefix string: Prefix added to select control subcomponent classnames. In most circumstances this should not be changed as it is used to style the compontents.
• args.searchDebounceDelay number: Search debounce delay, in milliseconds.
• args.additionalSearchArgs Object: Object of additional query string arguments to use with the API request.
• args.label ?string: Search control label, passed to .
• args.id ?string: Search control HTML ID attribute, passed to .
• args.defaultOptions ?Object[]: Array of hydrated objects to preload into the select as options.
• args.getSearchArgs ?Function: Function invoked to generate the query string arguments used when fetching results from the API. The callback function is passed the search string.
• args.getSearchURL ?Function: Function invoked to create the search URL used to fetch results. The function is passed the searchPath and generated query string arguments from getSearchArgs().
• args.hydrateValues ?Function: Function invoked to hydrate integer values. The function is passed the currently selected values, the searchPath, and an array of cached (and hydrated) objects previously loaded from the server.
• args.formatSearchResults ?Function: Function invoked to format results retrieved from the server. The function is passed an array of objects from the server. It should return an array of objects, each containing at least a value and label property.
• args.formatSearchResultLabel ?Function: Function invoked to format the display label for a result. The function is passed an object representing a single result and should return a string.
• args.formatSearchResultValue ?Function: Function invoked to format the saved value for a result. The function is passed an object representing a single result and should the value to be stored.
• args.selectProps ...*: Any remaining properties are passed to the component, {@link https://react-select.com/props#select-props}.

Returns

• StyledBaseControl: The component.

ButtonGroupControl

Button Group Control component

Similar to the experimental <RadioGroup> component from @wordpress/components but it allows passing in an array of options.

Related

• BaseControl https://github.com/WordPress/gutenberg/tree/trunk/packages/components/src/base-control

Parameters

• props Object: Component properties object.
• props.label string: Control label text.
• props.className string: Control element css class name attribute.
• props.id string: Control element ID attribute.
• props.onClick Function: Callback function when a button in the group is clicked.
• props.selected string: The value of the currently selected option.
• props.options Object[]: An array of objects used to create the buttons in the group. Each object should contain at least a "label" and "value" property and can optionally include an "icon" property.

Returns

• BaseControl: The rendered component.

CopyButton

A "click to copy" button.

Uses the useCopyToClipboard() hook with a on WP 5.8 & later, otherwise falls back to the deprecated .

Parameters

• args Object: Component arguments.
• args.buttonText string: Text to to display within the button.
• args.copyText string: Text to copy to the clipboard.
• args.tooltipText string: Text to use in the tooltip wrapper around the button.
• args.onCopy Function: Copy success callback function.
• args.buttonProps ...*: Remaining properties passed to the underlying component.

Returns

• Object: The copy button fragment.

PostSearchControl

Searchable element powered by a WordPress REST API users endpoint.

This component is a wrapper around the component. It is configured to search users via the WordPress user REST API endpoint.

Parameters

• args Object: Component arguments.
• args.postType string: Post type endpoint.
• args.baseSearchPath string: Base search path used to create the searchPath.
• args.searchPath ?string: API path used to perform the search. If passed, will be used instead of the path generated from args.postType and args.baseSearchPath.
• args.placeholder string: The placeholder displayed within an empty search control.
• args.className string: HTML class attribute added to the select control.
• args.formatSearchResultLabel ?Function: Function invoked to format the display label for a result. The function is passed
• args.additionalSearchArgs Object: An object representing a single result and should return a string.
• args.baseProps ...*: Any remaining properties are passed to the component.

Returns

• BaseSearchControl: The component.

UserSearchControl

Searchable element powered by a WordPress REST API users endpoint.

This component is a wrapper around the component. It is configured to search users via the WordPress user REST API endpoint.

Parameters

• args Object: Component arguments.
• args.searchPath string: Required. API path used to perform the search.
• args.placeholder string: The placeholder displayed within an empty search control.
• args.className string: HTML class attribute added to the select control.
• args.formatSearchResultLabel ?Function: Function invoked to format the display label for a result. The function is passed
• args.additionalSearchArgs Object: An object representing a single result and should return a string.
• args.baseProps ...*: Any remaining properties are passed to the component.

Returns

• BaseSearchControl: The component.