comment_form

Outputs a complete commenting form for use within a template.

Description

comment_form( (array) $args = array(), (null) $post_id = null ); 

Most strings and form fields may be controlled through the $args array passed into the function, while you may also choose to use the filter to modify the array of default fields if you'd just like to add a new one or remove a single field. All fields are also individually passed through a filter of the where $name is the key used in the array of fields.

Parameters (2)

0. $args — Optional. (array) => array()
The args.

Options

  • fields, (comment) => array()
    • author (string) => ''

      Comment author field HTML.

    • email (string) => ''

      Comment author email field HTML.

    • url (string) => ''

      Comment author URL field HTML.

  • comment_field (string) => ''

    The comment textarea field HTML.

  • must_log_in (string) => ''

    HTML element for a must be logged in to comment message.

  • logged_in_as (string) => ''

    HTML element for a logged in as [user] message.

  • comment_notes_before (string) => ''

    HTML element for a message displayed before the comment fields if the user is not logged in. Default Your email address will not be published...

  • comment_notes_after (string) => ''

    HTML element for a message displayed after the textarea field.

  • action (string) => ''

    The comment form element action attribute. Default /wp-comments-post.php..

  • id_form (string) => 'commentform'

    The comment form element id attribute.

  • id_submit (string) => 'submit'

    The comment submit element id attribute.

  • class_form (string) => 'comment-form'

    The comment form element class attribute.

  • class_submit (string) => 'submit'

    The comment submit element class attribute.

  • name_submit (string) => 'submit'

    The comment submit element name attribute.

  • title_reply (string) => 'Leave a Reply'

    The translatable reply button label.

  • title_reply_to (string) => 'Leave a Reply to %s'

    The translatable reply-to button label.

  • title_reply_before (string) => ''

    HTML displayed before the comment form title. Default:

    '.

  • title_reply_after (string) => ''

    HTML displayed after the comment form title. Default:..

  • cancel_reply_before (string) => ''

    HTML displayed before the cancel reply link.

  • cancel_reply_after (string) => ''

    HTML displayed after the cancel reply link.

  • cancel_reply_link (string) => 'Cancel reply'

    The translatable cancel reply button label.

  • label_submit (string) => 'Post a comment'

    The translatable submit button label.

  • submit_button (string) => ''

    HTML format for the Submit button. Default: $s" type="submit" id="%2$s" class="%3$s" value="%4$s" />'.

  • submit_field (string) => ''

    HTML format for the markup surrounding the Submit button and comment hidden fields. Default:

    %1$s %2$s', where %1$s is the submit button markup and %2$s is the comment hidden fields.

array(
    'fields,' => array(

        /**
         * Comment author field HTML.
         *
         * @type string
         * @default ''
         */
        'author' => '',

        /**
         * Comment author email field HTML.
         *
         * @type string
         * @default ''
         */
        'email' => '',

        /**
         * Comment author URL field HTML.
         *
         * @type string
         * @default ''
         */
        'url' => ''
    ),

    /**
     * The comment textarea field HTML.
     *
     * @type string
     * @default ''
     */
    'comment_field' => '',

    /**
     * HTML element for a 'must be logged in to comment' message.
     *
     * @type string
     * @default ''
     */
    'must_log_in' => '',

    /**
     * HTML element for a 'logged in as [user]' message.
     *
     * @type string
     * @default ''
     */
    'logged_in_as' => '',

    /**
     * HTML element for a message displayed before the comment fields if the user is not logged in.
     * Default 'Your email address will not be published.'.
     *
     * @type string
     * @default ''
     */
    'comment_notes_before' => '',

    /**
     * HTML element for a message displayed after the textarea field.
     *
     * @type string
     * @default ''
     */
    'comment_notes_after' => '',

    /**
     * The comment form element action attribute. Default '/wp-comments-post.php'.
     *
     * @type string
     * @default ''
     */
    'action' => '',

    /**
     * The comment form element id attribute.
     *
     * @type string
     * @default 'commentform'
     */
    'id_form' => 'commentform',

    /**
     * The comment submit element id attribute.
     *
     * @type string
     * @default 'submit'
     */
    'id_submit' => 'submit',

    /**
     * The comment form element class attribute.
     *
     * @type string
     * @default 'comment-form'
     */
    'class_form' => 'comment-form',

    /**
     * The comment submit element class attribute.
     *
     * @type string
     * @default 'submit'
     */
    'class_submit' => 'submit',

    /**
     * The comment submit element name attribute.
     *
     * @type string
     * @default 'submit'
     */
    'name_submit' => 'submit',

    /**
     * The translatable 'reply' button label.
     *
     * @type string
     * @default 'Leave a Reply'
     */
    'title_reply' => 'Leave a Reply',

    /**
     * The translatable 'reply-to' button label.
     *
     * @type string
     * @default 'Leave a Reply to %s'
     */
    'title_reply_to' => 'Leave a Reply to %s',

    /**
     * HTML displayed before the comment form title. Default: ''.
     *
     * @type string
     * @default ''
     */
    'title_reply_before' => '',

    /**
     * HTML displayed after the comment form title. Default: ''.
     *
     * @type string
     * @default ''
     */
    'title_reply_after' => '',

    /**
     * HTML displayed before the cancel reply link.
     *
     * @type string
     * @default ''
     */
    'cancel_reply_before' => '',

    /**
     * HTML displayed after the cancel reply link.
     *
     * @type string
     * @default ''
     */
    'cancel_reply_after' => '',

    /**
     * The translatable 'cancel reply' button label.
     *
     * @type string
     * @default 'Cancel reply'
     */
    'cancel_reply_link' => 'Cancel reply',

    /**
     * The translatable 'submit' button label.
     *
     * @type string
     * @default 'Post a comment'
     */
    'label_submit' => 'Post a comment',

    /**
     * HTML format for the Submit button. Default: ''.
     *
     * @type string
     * @default ''
     */
    'submit_button' => '',

    /**
     * HTML format for the markup surrounding the Submit button and comment hidden fields. Default:
     * '%1$s %2$s', where %1$s is the submit button markup and %2$s is the comment hidden fields.
     *
     * @type string
     * @default ''
     */
    'submit_field' => ''
);        

1. $post_id — Optional. (null) => null
Post ID or WP_Post object to generate the form for. Default current post.

Usage

  1. if ( !function_exists( 'comment_form' ) ) { 
  2. require_once ABSPATH . WPINC . '/comment-template.php'; 
  3.  
  4. // The args. 
  5. $args = array( 
  6. 'fields,' => array( 
  7. 'author' => '', 
  8. 'email' => '', 
  9. 'url' => '' 
  10. ), 
  11. 'comment_field' => '', 
  12. 'must_log_in' => '', 
  13. 'logged_in_as' => '', 
  14. 'comment_notes_before' => '', 
  15. 'comment_notes_after' => '', 
  16. 'action' => '', 
  17. 'id_form' => 'commentform', 
  18. 'id_submit' => 'submit', 
  19. 'class_form' => 'comment-form', 
  20. 'class_submit' => 'submit', 
  21. 'name_submit' => 'submit', 
  22. 'title_reply' => 'Leave a Reply', 
  23. 'title_reply_to' => 'Leave a Reply to %s', 
  24. 'title_reply_before' => '', 
  25. 'title_reply_after' => '', 
  26. 'cancel_reply_before' => '', 
  27. 'cancel_reply_after' => '', 
  28. 'cancel_reply_link' => 'Cancel reply', 
  29. 'label_submit' => 'Post a comment', 
  30. 'submit_button' => '', 
  31. 'submit_field' => '' 
  32. ); 
  33.  
  34. // Post ID or WP_Post object to generate the form for. Default current post. 
  35. $post_id = null; 
  36.  
  37. // NOTICE! Understand what this does before running. 
  38. $result = comment_form($args, $post_id); 
  39.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/comment-template.php  
  1. function comment_form( $args = array(), $post_id = null ) { 
  2. if ( null === $post_id ) 
  3. $post_id = get_the_ID(); 
  4.  
  5. // Exit the function when comments for the post are closed. 
  6. if ( ! comments_open( $post_id ) ) { 
  7. /** 
  8. * Fires after the comment form if comments are closed. 
  9. * @since 3.0.0 
  10. */ 
  11.  
  12. return; 
  13.  
  14. $commenter = wp_get_current_commenter(); 
  15. $user = wp_get_current_user(); 
  16. $user_identity = $user->exists() ? $user->display_name : ''; 
  17.  
  18. $args = wp_parse_args( $args ); 
  19. if ( ! isset( $args['format'] ) ) 
  20. $args['format'] = current_theme_supports( 'html5', 'comment-form' ) ? 'html5' : 'xhtml'; 
  21.  
  22. $req = get_option( 'require_name_email' ); 
  23. $aria_req = ( $req ? " aria-required='true'" : '' ); 
  24. $html_req = ( $req ? " required='required'" : '' ); 
  25. $html5 = 'html5' === $args['format']; 
  26. $fields = array( 
  27. 'author' => '<p class="comment-form-author">' . '<label for="author">' . __( 'Name' ) . ( $req ? ' <span class="required">*</span>' : '' ) . '</label> ' . 
  28. '<input id="author" name="author" type="text" value="' . esc_attr( $commenter['comment_author'] ) . '" size="30" maxlength="245"' . $aria_req . $html_req . ' /></p>',  
  29. 'email' => '<p class="comment-form-email"><label for="email">' . __( 'Email' ) . ( $req ? ' <span class="required">*</span>' : '' ) . '</label> ' . 
  30. '<input id="email" name="email" ' . ( $html5 ? 'type="email"' : 'type="text"' ) . ' value="' . esc_attr( $commenter['comment_author_email'] ) . '" size="30" maxlength="100" aria-describedby="email-notes"' . $aria_req . $html_req . ' /></p>',  
  31. 'url' => '<p class="comment-form-url"><label for="url">' . __( 'Website' ) . '</label> ' . 
  32. '<input id="url" name="url" ' . ( $html5 ? 'type="url"' : 'type="text"' ) . ' value="' . esc_attr( $commenter['comment_author_url'] ) . '" size="30" maxlength="200" /></p>',  
  33. ); 
  34.  
  35. $required_text = sprintf( ' ' . __('Required fields are marked %s'), '<span class="required">*</span>' ); 
  36.  
  37. /** 
  38. * Filters the default comment form fields. 
  39. * @since 3.0.0 
  40. * @param array $fields The default comment fields. 
  41. */ 
  42. $defaults = array( 
  43. 'fields' => $fields,  
  44. 'comment_field' => '<p class="comment-form-comment"><label for="comment">' . _x( 'Comment', 'noun' ) . '</label> <textarea id="comment" name="comment" cols="45" rows="8" maxlength="65525" aria-required="true" required="required"></textarea></p>',  
  45. /** This filter is documented in wp-includes/link-template.php */ 
  46. 'must_log_in' => '<p class="must-log-in">' . sprintf( 
  47. /** translators: %s: login URL */ 
  48. __( 'You must be <a href="%s">logged in</a> to post a comment.' ),  
  49. ) . '</p>',  
  50. /** This filter is documented in wp-includes/link-template.php */ 
  51. 'logged_in_as' => '<p class="logged-in-as">' . sprintf( 
  52. /** translators: 1: edit user link, 2: accessibility text, 3: user name, 4: logout URL */ 
  53. __( '<a href="%1$s" aria-label="%2$s">Logged in as %3$s</a>. <a href="%4$s">Log out?</a>' ),  
  54. /** translators: %s: user name */ 
  55. esc_attr( sprintf( __( 'Logged in as %s. Edit your profile.' ), $user_identity ) ),  
  56. $user_identity,  
  57. ) . '</p>',  
  58. 'comment_notes_before' => '<p class="comment-notes"><span id="email-notes">' . __( 'Your email address will not be published.' ) . '</span>'. ( $req ? $required_text : '' ) . '</p>',  
  59. 'comment_notes_after' => '',  
  60. 'action' => site_url( '/wp-comments-post.php' ),  
  61. 'id_form' => 'commentform',  
  62. 'id_submit' => 'submit',  
  63. 'class_form' => 'comment-form',  
  64. 'class_submit' => 'submit',  
  65. 'name_submit' => 'submit',  
  66. 'title_reply' => __( 'Leave a Reply' ),  
  67. 'title_reply_to' => __( 'Leave a Reply to %s' ),  
  68. 'title_reply_before' => '<h3 id="reply-title" class="comment-reply-title">',  
  69. 'title_reply_after' => '</h3>',  
  70. 'cancel_reply_before' => ' <small>',  
  71. 'cancel_reply_after' => '</small>',  
  72. 'cancel_reply_link' => __( 'Cancel reply' ),  
  73. 'label_submit' => __( 'Post Comment' ),  
  74. 'submit_button' => '<input name="%1$s" type="submit" id="%2$s" class="%3$s" value="%4$s" />',  
  75. 'submit_field' => '<p class="form-submit">%1$s %2$s</p>',  
  76. 'format' => 'xhtml',  
  77. ); 
  78.  
  79. /** 
  80. * Filters the comment form default arguments. 
  81. * Use {@see 'comment_form_default_fields'} to filter the comment fields. 
  82. * @since 3.0.0 
  83. * @param array $defaults The default comment form arguments. 
  84. */ 
  85. $args = wp_parse_args( $args, apply_filters( 'comment_form_defaults', $defaults ) ); 
  86.  
  87. // Ensure that the filtered args contain all required default values. 
  88. $args = array_merge( $defaults, $args ); 
  89.  
  90. /** 
  91. * Fires before the comment form. 
  92. * @since 3.0.0 
  93. */ 
  94. ?> 
  95. <div id="respond" class="comment-respond"> 
  96. <?php 
  97. echo $args['title_reply_before']; 
  98.  
  99. comment_form_title( $args['title_reply'], $args['title_reply_to'] ); 
  100.  
  101. echo $args['cancel_reply_before']; 
  102.  
  103. cancel_comment_reply_link( $args['cancel_reply_link'] ); 
  104.  
  105. echo $args['cancel_reply_after']; 
  106.  
  107. echo $args['title_reply_after']; 
  108.  
  109. if ( get_option( 'comment_registration' ) && !is_user_logged_in() ) : 
  110. echo $args['must_log_in']; 
  111. /** 
  112. * Fires after the HTML-formatted 'must log in after' message in the comment form. 
  113. * @since 3.0.0 
  114. */ 
  115. else : ?> 
  116. <form action="<?php echo esc_url( $args['action'] ); ?>" method="post" id="<?php echo esc_attr( $args['id_form'] ); ?>" class="<?php echo esc_attr( $args['class_form'] ); ?>"<?php echo $html5 ? ' novalidate' : ''; ?>> 
  117. <?php 
  118. /** 
  119. * Fires at the top of the comment form, inside the form tag. 
  120. * @since 3.0.0 
  121. */ 
  122.  
  123. if ( is_user_logged_in() ) : 
  124. /** 
  125. * Filters the 'logged in' message for the comment form for display. 
  126. * @since 3.0.0 
  127. * @param string $args_logged_in The logged-in-as HTML-formatted message. 
  128. * @param array $commenter An array containing the comment author's 
  129. * username, email, and URL. 
  130. * @param string $user_identity If the commenter is a registered user,  
  131. * the display name, blank otherwise. 
  132. */ 
  133. echo apply_filters( 'comment_form_logged_in', $args['logged_in_as'], $commenter, $user_identity ); 
  134.  
  135. /** 
  136. * Fires after the is_user_logged_in() check in the comment form. 
  137. * @since 3.0.0 
  138. * @param array $commenter An array containing the comment author's 
  139. * username, email, and URL. 
  140. * @param string $user_identity If the commenter is a registered user,  
  141. * the display name, blank otherwise. 
  142. */ 
  143. do_action( 'comment_form_logged_in_after', $commenter, $user_identity ); 
  144.  
  145. else : 
  146.  
  147. echo $args['comment_notes_before']; 
  148.  
  149. endif; 
  150.  
  151. // Prepare an array of all fields, including the textarea 
  152. $comment_fields = array( 'comment' => $args['comment_field'] ) + (array) $args['fields']; 
  153.  
  154. /** 
  155. * Filters the comment form fields, including the textarea. 
  156. * @since 4.4.0 
  157. * @param array $comment_fields The comment fields. 
  158. */ 
  159. $comment_fields = apply_filters( 'comment_form_fields', $comment_fields ); 
  160.  
  161. // Get an array of field names, excluding the textarea 
  162. $comment_field_keys = array_diff( array_keys( $comment_fields ), array( 'comment' ) ); 
  163.  
  164. // Get the first and the last field name, excluding the textarea 
  165. $first_field = reset( $comment_field_keys ); 
  166. $last_field = end( $comment_field_keys ); 
  167.  
  168. foreach ( $comment_fields as $name => $field ) { 
  169.  
  170. if ( 'comment' === $name ) { 
  171.  
  172. /** 
  173. * Filters the content of the comment textarea field for display. 
  174. * @since 3.0.0 
  175. * @param string $args_comment_field The content of the comment textarea field. 
  176. */ 
  177.  
  178. echo $args['comment_notes_after']; 
  179.  
  180. } elseif ( ! is_user_logged_in() ) { 
  181.  
  182. if ( $first_field === $name ) { 
  183. /** 
  184. * Fires before the comment fields in the comment form, excluding the textarea. 
  185. * @since 3.0.0 
  186. */ 
  187.  
  188. /** 
  189. * Filters a comment form field for display. 
  190. * The dynamic portion of the filter hook, `$name`, refers to the name 
  191. * of the comment form field. Such as 'author', 'email', or 'url'. 
  192. * @since 3.0.0 
  193. * @param string $field The HTML-formatted output of the comment form field. 
  194. */ 
  195. echo apply_filters( "comment_form_field_{$name}", $field ) . "\n"; 
  196.  
  197. if ( $last_field === $name ) { 
  198. /** 
  199. * Fires after the comment fields in the comment form, excluding the textarea. 
  200. * @since 3.0.0 
  201. */ 
  202.  
  203. $submit_button = sprintf( 
  204. $args['submit_button'],  
  205. esc_attr( $args['name_submit'] ),  
  206. esc_attr( $args['id_submit'] ),  
  207. esc_attr( $args['class_submit'] ),  
  208. esc_attr( $args['label_submit'] ) 
  209. ); 
  210.  
  211. /** 
  212. * Filters the submit button for the comment form to display. 
  213. * @since 4.2.0 
  214. * @param string $submit_button HTML markup for the submit button. 
  215. * @param array $args Arguments passed to `comment_form()`. 
  216. */ 
  217. $submit_button = apply_filters( 'comment_form_submit_button', $submit_button, $args ); 
  218.  
  219. $submit_field = sprintf( 
  220. $args['submit_field'],  
  221. $submit_button,  
  222. get_comment_id_fields( $post_id ) 
  223. ); 
  224.  
  225. /** 
  226. * Filters the submit field for the comment form to display. 
  227. * The submit field includes the submit button, hidden fields for the 
  228. * comment form, and any wrapper markup. 
  229. * @since 4.2.0 
  230. * @param string $submit_field HTML markup for the submit field. 
  231. * @param array $args Arguments passed to comment_form(). 
  232. */ 
  233. echo apply_filters( 'comment_form_submit_field', $submit_field, $args ); 
  234.  
  235. /** 
  236. * Fires at the bottom of the comment form, inside the closing </form> tag. 
  237. * @since 1.5.0 
  238. * @param int $post_id The post ID. 
  239. */ 
  240. do_action( 'comment_form', $post_id ); 
  241. ?> 
  242. </form> 
  243. <?php endif; ?> 
  244. </div><!-- #respond --> 
  245. <?php 
  246.  
  247. /** 
  248. * Fires after the comment form. 
  249. * @since 3.0.0 
  250. */