Hey, everyone! I have a fun, new hack for you that involves creating a full-width “widget” in your WordPress dashboard.

The dashboard widgets that come out of the box with WordPress include things like Quick Draft, At a Glance, Activity, WordPress News, etc. There are plugins that add dashboard widgets as well, such as JetPack and Gravity Forms.

What you’ve likely noticed about these dashboard widgets is that, by default, they’re in a columnized layout. The only “widget” that is always full-width is the Welcome box that you see after first installing WordPress, and most likely dismiss soon thereafter. However, this Welcome box is not technically a dashboard widget. It’s actually some simple markup that can be hidden with the dismiss button, whereas actual dashboard widgets are registered with special WordPress functions, and are toggled between states of opened and closed.

The quickest way to make a dashboard widget full-width is to switch the layout option (found under Screen Options) to one column. However, this will make all the dashboard widgets full-width. Personally, I like the 2-column view, but I’ve had the occasional need for only one full-width widget, usually for something relatively more important than the other widgets.

So how can I create just one full-width dashboard widget? Unfortunately, WordPress does not include anything for us to do that. If we register a dashboard widget via the wp_add_dashboard_widget() function, it’s going to behave like the rest of the widgets in that it will align based on the number of columns you set under Screen Options. If you’re like me, and prefer to keep the 2-column view, this means your custom dashboard widget cannot be full-width. Bummer.

The Hack!

I say this is a hack because it’s not the “cleanest” way of doing things, as we’re relying on jQuery to show the content. That said, it will get the job done, as long as JavaScript is not disabled.

What we’re going to do is replicate the Welcome box. Once it’s in place, we can customize the markup however we wish.

The reason we’re replicating the Welcome box is because the structure is already there, it’s styled, and it looks good. Once we add the markup, we’ll use jQuery to append it to the default Welcome box. This works because the default box is always in the dashboard markup, even when you dismiss it (it becomes hidden then).

Adding the HTML

You may know that there’s a welcome_panel hook available in WordPress. Unforutunately, this hook fires inside the default Welcome box, which means that anything we attach to it will display within the default box, and won’t be visible when it is dismissed. WordPress does not include a hook for executing code after the Welcome box. Therefore, we will add the HTML to the admin_footer hook, then use jQuery to reposition it. The following HTML is the markup for the default Welcome box (I’ve removed the dismiss element because we don’t need it).

This must be modified in a couple ways: the welcome-panel ID needs to be changed, and it needs to be hidden by default. The first line should then look like this:

<div id="custom-id" class="welcome-panel" style="display: none;">

After you’ve made those changes, you can then customize the inner markup.

The jQuery

The following can be added right after the last closing DIV in the HTML.

<script>
	jQuery(document).ready(function($) {
		$('#welcome-panel').after($('#custom-id').show());
	});
</script>

This is showing our newly added HTML, and adding it after the default Welcome box. Remember to change “custom-id” part in #custom-id to whatever ID you used in the step above.

The PHP

Lastly, we need to output our HTML and jQuery. Earlier, I mentioned doing this via the admin_footer hook. Since this hook runs on every admin page, we need to check if the current screen is the main dashboard screen. If it is, we’ll output everything. Otherwise, we won’t. Here’s the code in its entirety:

All done…enjoy!