Global Search

Quick Actions API

The Global Search Quick Actions API allows external plugins and themes to register, modify, or remove quick actions from the global search interface

Overview

Quick actions are displayed in the global search modal when users open the search interface (Cmd/Ctrl + K). They provide quick access to common tasks like creating new posts, navigating to the dashboard, or toggling settings.

The API uses a filter hook system similar to WordPress hooks, allowing plugins to modify the quick actions array before it's displayed.

Filter Hook

Hook Name

uixpress/search/quickActions/register

Hook Type

Filter Hook - Modifies the quick actions array

Hook Signature

addFilter('uixpress/search/quickActions/register', (actions) => {
  // Modify actions array
  return actions;
}, priority);

Parameters

actions (Array): The current array of quick action objects
priority (Number, optional): Priority for the filter (default: 10). Lower numbers run first.

Return Value

Returns an array of quick action objects.

Quick Action Object Structure

Each quick action must be an object with the following properties:

{
  id: string,           // Unique identifier for the action (required)
  name: string,         // Display name (required)
  icon: string,         // Icon name from icon system (required)
  action: Function,    // Function to execute when action is clicked (required)
  hidden: boolean      // Whether to hide the action (optional, default: false)
}

Properties

id (string, required)

Unique identifier for the action
Used to identify and filter actions
Should be namespaced (e.g., my-plugin/my-action)

name (string, required)

Display name shown in the quick actions list
Should be translatable using WordPress __() function

icon (string, required)

Icon name from the uiXpress icon system
See available icons in the icon component

action (Function, required)

Function executed when the action is clicked
Can perform any action (navigation, API calls, etc.)
Modal will automatically close after execution

hidden (boolean, optional)

Whether to hide the action from display
Default: false
Useful for conditional visibility

Usage Examples

Adding a New Quick Action

import { addFilter } from '@/assets/js/functions/HooksSystem.js';
// Or use window.uixpress.addFilter if outside Vue app

addFilter('uixpress/search/quickActions/register', (actions) => {
  return [
    ...actions,
    {
      id: 'my-plugin/create-product',
      name: __('Create Product', 'my-plugin'),
      icon: 'add',
      action: () => {
        window.location.href = '/wp-admin/post-new.php?post_type=product';
      },
    },
  ];
});

Removing a Quick Action

import { addFilter } from '@/assets/js/functions/HooksSystem.js';

addFilter('uixpress/search/quickActions/register', (actions) => {
  // Remove the "New Post" action
  return actions.filter((action) => action.id !== 'new-post');
});

Modifying an Existing Action

import { addFilter } from '@/assets/js/functions/HooksSystem.js';

addFilter('uixpress/search/quickActions/register', (actions) => {
  return actions.map((action) => {
    // Modify the "View Dashboard" action
    if (action.id === 'view-dashboard') {
      return {
        ...action,
        name: __('Go to Dashboard', 'my-plugin'),
        icon: 'dashboard',
      };
    }
    return action;
  });
});

Conditional Action Registration

import { addFilter } from '@/assets/js/functions/HooksSystem.js';

addFilter('uixpress/search/quickActions/register', (actions) => {
  const newActions = [...actions];

  // Only add action if user has specific capability
  if (window.uixpress?.state?.canManageOptions) {
    newActions.push({
      id: 'my-plugin/admin-tools',
      name: __('Admin Tools', 'my-plugin'),
      icon: 'settings',
      action: () => {
        window.location.href = '/wp-admin/admin.php?page=my-plugin-tools';
      },
    });
  }

  return newActions;
});

Using Priority to Control Order

import { addFilter } from '@/assets/js/functions/HooksSystem.js';

// High priority - runs first, adds action at the beginning
addFilter(
  'uixpress/search/quickActions/register',
  (actions) => {
    return [
      {
        id: 'my-plugin/important-action',
        name: __('Important Action', 'my-plugin'),
        icon: 'star',
        action: () => {
          // Do something important
        },
      },
      ...actions,
    ];
  },
  5 // Low priority number = runs first
);

// Low priority - runs last, adds action at the end
addFilter(
  'uixpress/search/quickActions/register',
  (actions) => {
    return [
      ...actions,
      {
        id: 'my-plugin/less-important-action',
        name: __('Less Important', 'my-plugin'),
        icon: 'info',
        action: () => {
          // Do something less important
        },
      },
    ];
  },
  20 // High priority number = runs last
);

Default Quick Actions

The following quick actions are registered by default:

new-post - Create a new post
new-page - Create a new page
view-dashboard - Navigate to dashboard
view-site - View the frontend site
site-settings - Open site settings (only if user has manage_options capability)
dark-mode - Switch to dark mode (context-aware visibility)
light-mode - Switch to light mode (context-aware visibility)

Event System

The search component dispatches a custom event when it's ready for plugin registration:

document.addEventListener('uixpress/search/ready', () => {
  // Search component is ready, safe to register actions
  addFilter('uixpress/search/quickActions/register', (actions) => {
    // Register your actions
    return actions;
  });
});

Best Practices

1. Namespace Your Action IDs

Always prefix your action IDs with your plugin/theme name to avoid conflicts:

{
  id: 'my-plugin/my-action', // Good
  // Not: 'my-action' // Bad - could conflict
}

2. Use Translatable Strings

Always use WordPress translation functions for action names:

{
  name: __('My Action', 'my-plugin'), // Good
  // Not: 'My Action' // Bad - not translatable
}

3. Handle Errors Gracefully

Wrap your action functions in error handling:

{
  action: () => {
    try {
      // Your action code
    } catch (error) {
      console.error('Action failed:', error);
      // Show user-friendly error message
    }
  },
}

4. Check Permissions

Verify user capabilities before registering actions:

addFilter('uixpress/search/quickActions/register', (actions) => {
  // Check if user has required capability
  if (!window.uixpress?.state?.canManageOptions) {
    return actions; // Don't add admin-only actions
  }

  return [...actions, myAdminAction];
});

5. Use Appropriate Icons

Choose icons that clearly represent the action:

add - For create/new actions
settings - For settings/configuration
home - For navigation to home/dashboard
edit - For editing actions
See icon component for full list

Integration with WordPress Plugins

PHP Plugin Integration

If you're building a WordPress plugin, you can enqueue JavaScript that registers actions:

add_action('admin_enqueue_scripts', function() {
    wp_enqueue_script(
        'my-plugin-search-actions',
        plugin_dir_url(__FILE__) . 'assets/search-actions.js',
        ['uixpress-search'], // Depend on uiXpress search
        '1.0.0',
        true
    );
});

Then in your JavaScript file:

// Wait for search to be ready
document.addEventListener('uixpress/search/ready', () => {
  if (window.uixpress?.addFilter) {
    window.uixpress.addFilter('uixpress/search/quickActions/register', (actions) => {
      return [
        ...actions,
        {
          id: 'my-plugin/my-action',
          name: myPluginData.translations.myAction, // From wp_localize_script
          icon: 'add',
          action: () => {
            window.location.href = myPluginData.adminUrl + 'post-new.php';
          },
        },
      ];
    });
  }
});