wp_nonce_field( int|string $action = -1, string $name = '_wpnonce', bool $referer = true, bool $display = true ): string
- Since
- 2.0.4
- Source
wp-includes/functions.php:1899
Outputs a hidden `<input>` field containing a nonce generated for the given $action, and appends a referer field unless $referer is set to false. Pass $display as false to get the markup back as a string instead of having it echoed immediately, which is useful when you're assembling a form in a buffer or a REST/AJAX response. Pair it with check_admin_referer() or wp_verify_nonce() on submission, using the same $action and $name values you passed here.
Description
The nonce field is used to validate that the contents of the form came from the location on the current site and not somewhere else. The nonce does not offer absolute protection, but should protect against most cases. It is very important to use nonce field in forms.
The $action and $name are optional, but if you want to have better security, it is strongly suggested to set those two parameters. It is easier to just call the function without any parameters, because validation of the nonce doesn't require any parameters, but since crackers know what the default is it won't be difficult for them to find a way around your nonce and cause damage.
The input name will be whatever $name value you gave. The input value will be the nonce creation value.
Compatibility
- WordPress
- since 2.0.4
- PHP
- 7.4–8.6-dev
- 6.7.7
- 6.8.8
- 6.9.7
- 7.0.4
- 7.1.0
Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.
Parameters
$actionint|stringoptional- Action name. Default -1.Default:
-1 $namestringoptional- Nonce name. Default '_wpnonce'.Default:
'_wpnonce' $refererbooloptional- Whether to set the referer field for validation. Default true.Default:
true $displaybooloptional- Whether to display or return hidden form field. Default true.Default:
true
Return value
string- Nonce field HTML markup.
Code examples
Every example is editable and runs in a real WordPress booted in your browser by WordPress Playground. Press Run, then edit the code: clicking away re-runs it. Nothing is sent anywhere until you do.
Add a nonce field to a custom admin form that updates post meta
Render a small form for editing the price meta on post 2, protected by a nonce tied to that specific post and action.
echo '<form method="post" action="">';
wp_nonce_field( 'update_price_2', 'price_nonce' );
echo '<input type="hidden" name="post_id" value="2" />';
echo '<input type="text" name="price" value="' . esc_attr( get_post_meta( 2, 'price', true ) ) . '" />';
echo '</form>';
echo esc_html( 'Nonce field rendered above, scoped to the update_price_2 action.' );The action string includes the post ID so a nonce copied from one post's edit form cannot be reused on another post's form.
Capture the nonce field markup as a string instead of echoing it
Set $display to false to get the HTML back without it being printed, then inspect or reuse the markup yourself.
$nonce_html = wp_nonce_field( 'export_prices', 'export_nonce', true, false );
echo '<p>Generated markup (not yet output by the function itself):</p>';
echo esc_html( $nonce_html );With $display false, wp_nonce_field() no longer echoes anything on its own, only the return value contains the markup.
Common problems and fixes · 4
- Why does my form end up with the nonce field twice?
- Why does check_admin_referer() say the nonce is invalid even though the field is there?
- Is it safe to just call wp_nonce_field() with no arguments?
- Why is there an extra _wp_http_referer field I didn't add?
Why does my form end up with the nonce field twice?
Why does check_admin_referer() say the nonce is invalid even though the field is there?
Is it safe to just call wp_nonce_field() with no arguments?
Why is there an extra _wp_http_referer field I didn't add?
Alternatives and related functions
wp_create_nonce- When you only need the raw nonce value (for example to put in a URL query string or a JS variable) rather than a ready-made hidden form field.
wp_nonce_url- When the nonce needs to be attached to a link's query string instead of a form field.
wp_verify_nonce- When you're on the receiving end of the form and need to check the nonce yourself without the redirect-and-die behavior of check_admin_referer().
check_admin_referer- When you want the nonce and referer created by wp_nonce_field() verified in one call that stops execution automatically on failure.
Performance profile
How much work a call to wp_nonce_field() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.
- Cost class
- Trivial
- Scaling
- Constant
- Instructions
- 20–25
- Plugin surface
- None
- Called by
- 42
Touches nothing outside its own arguments.
No loop in the body: the same number of instructions runs whatever you pass in.
Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 25.
Nothing here hands control to plugin code.
42 places in core call this, so the cost is paid more often than your own code shows.
What it touches
- hookthird-party callbacks
apply_filters()one call below wp_nonce_field()
Further down the call graph this can also reach option, cache, serialize, transient and query. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.
What one call costs · 2 distinct outcomes
One number would be a lie: the work depends on which branch runs. These are every distinct cost wp_nonce_field() can have, taken from its control-flow graph on PHP 8.5.
| When | Instructions | Calls it makes |
|---|---|---|
| always | 20–21 | esc_attr(), wp_create_nonce() |
| always | 24–25 | esc_attr(), wp_create_nonce(), wp_referer_field() |
Across PHP versions
Compiles the same on PHP 7.4, 8.1, 8.2, 8.3, 8.4, 8.5 and 8.6-dev: 25 instructions, 20–25 executed per call, 2 branches. The work does not change between versions.
An instruction is not a fixed amount of time, so a matching count is not necessarily the same speed; what it rules out is a difference in the work itself.
Uses · 3
- esc_attr()Escaping for HTML attributes.
- wp_create_nonce()Creates a cryptographic token tied to a specific action, user, user session, and window of time.
- wp_referer_field()Retrieves or displays referer hidden field for forms.
Used by · 42
- Custom_Background::admin_page()Displays the custom background page.
- Custom_Image_Header::step_1()Displays first step of custom header image page.
- Custom_Image_Header::step_2()Displays second step of custom header image page.
- WP_Comments_List_Table::display()Displays the comments table.
- WP_Comments_List_Table::extra_tablenav()
- WP_List_Table::display_tablenav()Generates the table navigation above or below the table
- WP_Post_Comments_List_Table::display()
- WP_Posts_List_Table::inline_edit()Outputs the hidden row displayed when inline editing
- WP_Screen::render_screen_options()Renders the screen options tab.
- WP_Terms_List_Table::inline_edit()Outputs the hidden row displayed when inline editing
- WP_Theme_Install_List_Table::display()Displays the theme install table.
- WP_Themes_List_Table::display()Displays the themes table.
Show all 42
- _WP_Editors::wp_link_dialog()Dialog for internal linking.
- _list_meta_row()Outputs a single row of public meta data in the Custom Fields meta box.
- _wp_dashboard_control_callback()Outputs controls for the current dashboard widget.
- admin_color_scheme_picker()Displays the default administration color scheme picker (Used in user-edit.php).
- confirm_delete_users()
- find_posts_div()Outputs the modal window used for attaching media to posts or pages in the media-listing screen.
- install_plugins_upload()Displays a form to upload plugins from zip files.
- install_themes_upload()Displays a form to upload themes from zip files.
- link_categories_meta_box()Displays link categories form fields.
- list_core_update()Lists available core updates.
- list_plugin_updates()Display the upgrade plugins form.
- list_theme_updates()Display the upgrade themes form.
- list_translation_updates()Display the update translations form.
- media_upload_gallery_form()Adds gallery form to upload iframe.
- media_upload_library_form()Outputs the legacy media upload form for the media library.
- media_upload_type_form()Outputs the legacy media upload form for a given media type.
- media_upload_type_url_form()Outputs the legacy media upload form for external media.
- meta_form()Prints the form in the Custom Fields meta box.
- network_step1()Prints step 1 for Network installation process.
- post_categories_meta_box()Displays post categories form fields.
- post_comment_meta_box()Displays comments for post.
- request_filesystem_credentials()Displays a form to the user to request for their FTP/SSH details in order to connect to the filesystem.
- settings_fields()Outputs nonce, action, and option_page fields for a settings page.
- signup_nonce_fields()Adds a nonce field to the signup page.
- the_block_editor_meta_box_post_form_hidden_fields()Renders the hidden form required for the meta boxes form.
- the_block_editor_meta_boxes()Renders the meta boxes forms.
- wp_comment_form_unfiltered_html_nonce()Displays form token for unfiltered comments.
- wp_comment_reply()Outputs the in-line comment reply-to form in the Comments list table.
- wp_dashboard()Displays the dashboard.
- wp_dashboard_quick_press()Displays the Quick Draft widget.
Source code
function wp_nonce_field( $action = -1, $name = '_wpnonce', $referer = true, $display = true ) { $name = esc_attr( $name ); $nonce_field = '<input type="hidden" id="' . $name . '" name="' . $name . '" value="' . wp_create_nonce( $action ) . '" />'; if ( $referer ) { $nonce_field .= wp_referer_field( false ); } if ( $display ) { echo $nonce_field; } return $nonce_field;}Changelog
Introduced in 2.0.4. Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
About this page
- Parsed data
- Generated from the wordpress-develop 6.9.7 tag, from
src/wp-includes/functions.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it. - Corrections
- Something wrong on this page? Report it and it gets fixed in the next regeneration.