WordPress at a glance
Home Handbook WP-CLI Commands

wp widget

Manages widgets, including adding and moving them within sidebars.

Commands Description
Lists widgets associated with a sidebar.
Adds a widget to a sidebar.
Updates options for an existing widget.
Moves the position of a widget.
Deactivates one or more widgets from an active sidebar.
Deletes one or more widgets from a sidebar.
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


menu

wp widget list

Lists widgets associated with a sidebar.

Usage

wp widget list {sidebar-id} [--fields={fields}] [--format={format}]

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
menu

wp widget add

Adds a widget to a sidebar.

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

Usage

wp widget add {name} {sidebar-id} [{position}] [--{field}={value}]

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.

wp widget update

Updates options for an existing widget.

Usage

wp widget update {widget-id} [--{field}={value}]

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.

wp widget move

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 {widget-id} [--position={position}] [--sidebar-id={sidebar-id}]

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.

wp widget deactivate

Deactivates one or more widgets from an active sidebar.

Moves widgets to Inactive Widgets.

Usage

wp widget deactivate {widget-id}...

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.

wp widget delete

Deletes one or more widgets from a sidebar.

Usage

wp widget delete {widget-id}...

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.

wp widget reset

Resets sidebar.

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

Usage

wp widget reset [{sidebar-id}...] [--all]

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.