devLap

How to Use the `bricks/form/custom_action` Hook in Bricks Builder

php dev.to

How to Use the bricks/form/custom_action Hook in Bricks Builder

You can run custom PHP code after a Bricks Builder form submission using the bricks/form/custom_action hook. This is ideal if you need to send emails, save entries, or connect with external services.

Step 1: Set Up the Form Action

In your Bricks Builder form settings, go to "Actions after successful form submit" and select Custom.

Step 2: Write Your PHP Logic

Add this code to your theme's functions.php file or use a WordPress code snippets plugin.

// Hook your function to the Bricks custom action
add_action('bricks/form/custom_action', 'my_form_custom_action', 10, 1);

function my_form_custom_action($form) {
    // Get all submitted form fields as an array
    $fields = $form->get_fields(); // Example: ['name' => 'Jane', 'email' => 'jane@example.com']

    // Always check the form ID so your code only runs for the intended form
    $form_id = isset($fields['formId']) ? $fields['formId'] : '';

    if ($form_id !== 'replace_with_your_form_id') {
        // Not the intended form — stop here
        return;
    }

    // Custom logic goes here!
    // Example: integrate with an API, save a post, or trigger a notification

    // Set a user-facing message after submit
    $form->set_result([
        'action'  => 'my_custom_action',
        'type'    => 'success', // 'success', 'error', or 'info'
        'message' => esc_html__('Custom action executed!', 'your-textdomain'),
    ]);
}
Enter fullscreen mode Exit fullscreen mode

Helpful Notes for Junior Devs

  • Always check formId — This ensures your code only runs for the correct form, especially if you use custom actions on more than one form.
  • $form->get_fields() returns every value submitted by the user. Use it to process, validate, or forward data to external tools.
  • $form->set_result() controls what users see after submitting. Always provide friendly messages and handle errors gracefully.
  • For external integrations (webhooks, APIs), use WordPress's built-in wp_remote_post() rather than raw curl.
  • Replace all placeholder form IDs and field keys with the actual values from your Bricks form setup.

Example: Creating a WordPress Comment from Form Submission 

add_action('bricks/form/custom_action', 'create_comment_from_form', 10, 1);

function create_comment_from_form($form) {
    $fields = $form->get_fields();

    // Only execute for the intended form
    if ($fields['formId'] !== 'myformid') return;

    // Prepare comment data from submitted fields
    $comment_data = [
        'comment_post_ID'      => $fields['postid'],
        'comment_author'       => $fields['name'],
        'comment_author_email' => $fields['email'],
        'comment_content'      => $fields['comment'],
        'comment_approved'     => 1,
    ];

    try {
        wp_insert_comment(wp_slash($comment_data));

        $form->set_result([
            'action'  => 'my_custom_action',
            'type'    => 'success',
            'message' => esc_html__('Comment created!', 'your-textdomain'),
        ]);
    } catch (Exception $e) {
        $form->set_result([
            'action'  => 'my_custom_action',
            'type'    => 'error',
            'message' => esc_html__('Something went wrong. Please try again.', 'your-textdomain'),
        ]);

        // Log the actual error server-side for debugging
        error_log('Bricks form error: ' . $e->getMessage());
    }
}
Enter fullscreen mode Exit fullscreen mode

Note on error messages: Avoid exposing raw exception messages to users with $e->getMessage() — they can leak implementation details. Log errors server-side and show a generic message to the user instead.

Source: dev.to

arrow_back Back to Tutorials