wp widget

Manages widgets, including adding and moving them within sidebars.

Commands	Description
wp widget list	Lists widgets associated with a sidebar.
wp widget add	Adds a widget to a sidebar.
wp widget update	Updates options for an existing widget.
wp widget move	Moves the position of a widget.
wp widget deactivate	Deactivates one or more widgets from an active sidebar.
wp widget delete	Deletes one or more widgets from a sidebar.
wp widget reset	Resets sidebar.

Examples

# List widgets on a given sidebar
$ wp widget list sidebar-1
+----------+------------+----------+----------------------+
| name     | id         | position | options              |
+----------+------------+----------+----------------------+
| meta     | meta-6     | 1        | {"title":"Meta"}     |
| calendar | calendar-2 | 2        | {"title":"Calendar"} |
+----------+------------+----------+----------------------+

# Add a calendar widget to the second position on the sidebar
$ wp widget add calendar sidebar-1 2
Success: Added widget to sidebar.

# Update option(s) associated with a given widget
$ wp widget update calendar-1 --title="Calendar"
Success: Widget updated.

# Delete one or more widgets entirely
$ wp widget delete calendar-2 archive-1
Success: 2 widgets removed from sidebar.

Source code of the commands

wp-cli/widget-command
- Widget_Command.php

Lists widgets associated with a sidebar.

Usage

wp widget list

You can specify global options and the following:

{sidebar-id}

ID for the corresponding sidebar.

[--fields={fields}]

Limit the output to specific object fields.

[--format={format}]

Render output in a particular format.
Default: table
Can be:

table
csv
ids
json
count
yaml

Available fields

These fields will be displayed by default for each widget:

name
id
position
options

There are no optionally available fields.

Examples

$ wp widget list sidebar-1 --fields=name,id --format=csv
name,id
meta,meta-5
search,search-3

Adds a widget to a sidebar.

Creates a new widget entry in the database, and associates it with the sidebar.

Usage

wp widget add

You can specify global options and the following:

{name}: Widget name.
{sidebar-id}: ID for the corresponding sidebar.
[{position}]: Widget's current position within the sidebar. Defaults to last
[--{field}={value}]: Widget option to add, with its new value

Examples

# Add a new calendar widget to sidebar-1 with title "Calendar"
$ wp widget add calendar sidebar-1 2 --title="Calendar"
Success: Added widget to sidebar.

Updates options for an existing widget.

Usage

wp widget update

You can specify global options and the following:

{widget-id}: Unique ID for the widget
[--{field}={value}]: Field to update, with its new value

Examples

# Change calendar-1 widget title to "Our Calendar"
$ wp widget update calendar-1 --title="Our Calendar"
Success: Widget updated.

Moves the position of a widget.

Changes the order of a widget in its existing sidebar, or moves it to a new sidebar.

Usage

wp widget move

You can specify global options and the following:

{widget-id}: Unique ID for the widget
[--position={position}]: Assign the widget to a new position.
[--sidebar-id={sidebar-id}]: Assign the widget to a new sidebar

Examples

# Change position of widget
$ wp widget move recent-comments-2 --position=2
Success: Widget moved.

# Move widget to Inactive Widgets
$ wp widget move recent-comments-2 --sidebar-id=wp_inactive_widgets
Success: Widget moved.

Deactivates one or more widgets from an active sidebar.

Moves widgets to Inactive Widgets.

Usage

wp widget deactivate

You can specify global options and the following:

{widget-id}...: Unique ID for the widget(s)

Examples

# Deactivate the recent-comments-2 widget.
$ wp widget deactivate recent-comments-2
Success: 1 widget deactivated.

Deletes one or more widgets from a sidebar.

Usage

wp widget delete

You can specify global options and the following:

{widget-id}...: Unique ID for the widget(s)

Examples

# Delete the recent-comments-2 widget from its sidebar.
$ wp widget delete recent-comments-2
Success: Deleted 1 of 1 widgets.

Resets sidebar.

Removes all widgets from the sidebar and places them in Inactive Widgets.

Usage

wp widget reset

You can specify global options and the following:

[{sidebar-id}...]: One or more sidebars to reset.
[--all]: If set, all sidebars will be reset.

Examples

# Reset a sidebar
$ wp widget reset sidebar-1
Success: Sidebar 'sidebar-1' reset.

# Reset multiple sidebars
$ wp widget reset sidebar-1 sidebar-2
Success: Sidebar 'sidebar-1' reset.
Success: Sidebar 'sidebar-2' reset.

# Reset all sidebars
$ wp widget reset --all
Success: Sidebar 'sidebar-1' reset.
Success: Sidebar 'sidebar-2' reset.
Success: Sidebar 'sidebar-3' reset.