4.7.x theme.inc theme_username($object)
5.x theme.inc theme_username($object)
6.x theme.inc theme_username($object)
7.x theme.inc theme_username($variables)

Returns HTML for a username, potentially linked to the user's page.


$variables: An associative array containing:

  • account: The user object to format.
  • name: The user's name, sanitized.
  • extra: Additional text to append to the user's name, sanitized.
  • link_path: The path or URL of the user's profile page, home page, or other desired page to link to for more information about the user.
  • link_options: An array of options to pass to the l() function's $options parameter if linking the user's name to the user's page.
  • attributes_array: An array of attributes to pass to the drupal_attributes() function if not linking to the user's page.

See also



Related topics

21 theme calls to theme_username()
comment_admin_overview in modules/comment/comment.admin.inc
Form builder for the comment overview administration form.
contact_personal_form in modules/contact/contact.pages.inc
Form constructor for the personal contact form.
dblog_event in modules/dblog/dblog.admin.inc
Page callback: Displays details about a specific database log message.
dblog_overview in modules/dblog/dblog.admin.inc
Page callback: Displays a listing of database log messages.
hook_search_execute in modules/search/search.api.php
Execute a search for a set of key words.

... See full list


includes/theme.inc, line 2328
The theme system, which controls the output of Drupal.


function theme_username($variables) {
  if (isset($variables['link_path'])) {

    // We have a link path, so we should generate a link using l().
    // Additional classes may be added as array elements like
    // $variables['link_options']['attributes']['class'][] = 'myclass';
    $output = l($variables['name'] . $variables['extra'], $variables['link_path'], $variables['link_options']);
  else {

    // Modules may have added important attributes so they must be included
    // in the output. Additional classes may be added as array elements like
    // $variables['attributes_array']['class'][] = 'myclass';
    $output = '<span' . drupal_attributes($variables['attributes_array']) . '>' . $variables['name'] . $variables['extra'] . '</span>';
  return $output;


szantog’s picture

This print the current logged in user's with link:

global $user;
print t('!username logged in', array('!username' => theme('username', array('account' => $user)))),
Matt-H’s picture

Setting values into $variables['name'] or $variables['extra'] (array('name' => ..., 'extra' => ...) ) won't work under the default implementation, due to template_preprocess_username(). It has code:

$variables['extra'] = '';
$name = $variables['name_raw'] = format_username($account);
$variables['name'] = check_plain($name);

This code overrides anything set in $variables['name'] and $variables['extra'].

The only ways I can see to put in a custom name would be to either

  1. Remove the preprocess function from the registry so it doesn't run
  2. Change the name property on the account before sending it to $variables['account'];
  3. Make up some other properties in the $variables array (like 'name_real' and 'other_real') to send in a custom implementation of theme_username and use them.

None of these options are ideal.

Edit: $variables['link_path'] is also overridden.

rayasa’s picture

If you just want custom output then you need to override this function in your theme. I tried overriding the theme_username function and it works as expected.
Please refer http://drupal.org/node/173880 for more information.

Matt-H’s picture

My point is that, if using the theme_username's default implementation does not respect the values sent in the associative array. If I have

theme('username', array('name' => 'Custom Name'));

that "Custom Name" will not be displayed because the $variables array will be run through template_preprocess_username() and have its array's values will be altered. (Same with $variables['link_path'] and $variables['extra'].) Yes, I could make a custom theme override function for theme_username() and template_preprocess_username() and make it work, one way or another, but in my opinion, if the default implementation isn't going to work the way it is documented, either the function should be made so it does work, or the documentation should be updated to state that these values are set in the preprocess function, not by the associative array sent to the function.

mxh’s picture

To change the default display of your user account, change it with hook_username_alter

NancyDru’s picture

Issues should be posted in the issue queue, not here.

Diogenes’s picture

Suppose that someone suggests (or demands) that you use theme_username() instead of $user->name because it's the Drupal way.

Of course, you are not supposed to invoke theme_username() directly because that is NOT the Drupal way. Instead use...

theme('username', $variables);

This may not work as you expect. So WTF is $variables anyway? Here is what you might have to do to get things to actually work...

 * Implements hook_block_view_alter().
 * Changes the block title on the User menu and Navigation block. D6 already had
 * this feature, this code adds it to D7.
function mymodule_block_view_alter(&$data, $block) {
  global $user;

  if ($block->delta == 'user-menu' || $block->delta == 'navigation') {
    $uid = $user->uid;
    $account = array('account' => user_load($uid));
    $data['subject'] = isset($user->name) ? theme('username', $account) : $data['subject'];

For those of you that are asking themselves, after looking at the code snippet above; WTF? -- Hey don't shoot me, I am only the messenger.

Welcome to the Drupal Developer Experience (DX)!

steven.wichers’s picture

If you cut out the code specific to your implementation there then the remaining bit is:

theme('username', array('account' => $user));

Which is exactly like calling every other theme, so I'm not following where the problem comes from. I'm not sure where you got that code snippet, but it has a lot of superfluous stuff in it to start with before you even get to the call to theme().

joachim’s picture

I probably shouldn't pick this apart, but the reason this is terrible DX is that it's crammed with mistakes!!

  global $user;
  // ...
  $account = array('account' => user_load($uid));

You have the $user a moment ago! Why load it again?

    $data['subject'] = isset($user->name) ? theme('username', $account) : $data['subject'];

This is pointlessly hard to read. If you only want to set a variable if a condition is satisfied, and leave it alone otherwise, then don't use assignment with the ?: operator!

Just do:

if (condition) {
  $foo = bar;

And isset($user->name) -- you're checking for the anonymous user I take it? Then much simpler to check whether $user->uid evaluates to FALSE.

kienan91’s picture

Hi ! I have problem , I want $variables['extra'] display before $variables['name'] ! How to change it ? Thanks

tatarbj’s picture

In D7 core theme_username is actively used with a non-user object as account, they are even not called $user or $account or something similar. The documentation here should be changed from 'The user object to format.' to 'The object that refers to the user.' or something similar because now it confuses and lets you misunderstand how it really works.
Because in https://api.drupal.org/api/drupal/includes%21theme.inc/function/template... the account variable is formatted by https://api.drupal.org/api/drupal/includes%21common.inc/function/format_... that doesn't check anything else, only does the object have a ->name property or not.
Reference issue: https://www.drupal.org/node/2114089