Manages widgets, including adding and moving them within sidebars.

A widget adds content and features to a widget area (also called a sidebar).

Subcommands

wp widget add

Adds a widget to a sidebar.

Synopsis

wp widget add <name> <sidebar-id> [<position>] [--<field>=<value>]

Options

<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 list

Lists widgets associated with a sidebar.

Synopsis

wp widget list <sidebar-id> [--fields=<fields>] [--format=<format>]

Options

<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. Options: table, csv, ids, json, count, yaml.

Available Fields

Default fields: name, id, position, options.

Examples

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

wp widget move

Moves the position of a widget.

Synopsis

wp widget move <widget-id> [--position=<position>] [--sidebar-id=<sidebar-id>]

Options

<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 delete

Deletes one or more widgets from a sidebar.

Synopsis

wp widget delete <widget-id>...

Options

<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 deactivate

Deactivates one or more widgets from an active sidebar.

Moves widgets to Inactive Widgets.

Synopsis

wp widget deactivate <widget-id>...

Options

<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 update

Updates options for an existing widget.

Synopsis

wp widget update <widget-id> [--<field>=<value>]

Options

<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 reset

Resets sidebar.

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

Synopsis

wp widget reset [<sidebar-id>...] [--all]

Options

[<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.

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.