Theming with Twenty Seventeen

In 4.7, WordPress gets a new default theme: Twenty Seventeen. Like all default themes, it’s easily customizable for users and developers. This post will cover developer features and a few tricks when customizing the theme.

Of note

Override enqueued styles and scripts

With the use of get_theme_file_uri, introduced in 4.7, Twenty Seventeen lets child themes override styles and scripts with ease. For example, if you want to replace the theme’s global.js file, you can do so by including the same file in your child theme in the same path.


Twenty Seventeen includes a handful of filters, all of which are documented in line in the code.

Content width

The value is filterable in the event a child theme needs to change it.

function childtheme_content_width( $content_width ) {
    if ( twentyseventeen_is_frontpage() ) {
        $content_width = 960;
    return $content_width;
add_filter( 'twentyseventeen_content_width', 'childtheme_content_width' );

Custom header settings

Like past default themes, Twenty Seventeen filters the arguments for add_theme_support( 'custom-header' );. These can be changed in a child theme. Here, we’ll add flex-width to the current args.

function childtheme_custom_header_args( $args ) {
    $args['flex-width'] = true;
    return $args;
add_filter( 'twentyseventeen_custom_header_args', 'childtheme_custom_header_args' );

Header video settings

The theme changes the default provided by Core, but that can be modified by a child theme. Here, we change the text on the button in a child theme:

function childtheme_setup() {
    remove_filter( 'header_video_settings', 'twentyseventeen_video_controls' );
add_action( 'after_setup_theme', 'childtheme_setup' );

function childtheme_video_controls( $settings ) {
	$settings['l10n']['play'] = '__( 'Play my awesome video', 'childtheme' );
	$settings['l10n']['pause'] = '__( 'Pause my awesome video', 'childtheme' );
	return $settings;
add_filter( 'header_video_settings', 'childtheme_video_controls' );

Front page sections

Twenty Seventeen uses the Customizer to add sections to the front page. These are filterable with the twentyseventeen_front_page_sections filer. They can changed like so:

function childtheme_front_page_sections() {
	return 6;
add_filter( 'twentyseventeen_front_page_sections', 'childtheme_front_page_sections' );

With 6 being a new number there. In this way, the number of sections can be adjusted in a child theme.


One of the theme’s most notable behind-the-scenes features, the use of SVGs means better accessibility for icons, they look great on any device and they’re easier to customize.

First, the list of social link icons is filterable, so child themes can change it.

function childtheme_social_links_icons( $social_links_icons ) {
    $social_links_icons[''] = 'mysocialsite';
    return $social_links_icons;
add_filter( 'twentyseventeen_social_links_icons', 'childtheme_social_links_icons' );

All of Twenty Seventeen’s icons are decorative in nature. But if a child theme wanted to include an icon that needed to be described in an accessible way, it can thanks to built-in options.

These examples are documented in the code itself. However, for example:

Using a title:

<?php echo twentyseventeen_get_svg( array( 'icon' => 'arrow-right', 'title' => __( 'This is title', 'childtheme' ) ) ); ?>

Another example with title and desc (description):

<?php echo twentyseventeen_get_svg( array( 'icon' => 'arrow-right', 'title' => __( 'This is title', 'childtheme' ), 'desc' => __( 'This is longer desc', 'textdomain' ) ) ); ?>

For more information on SVG accessibility, see Using ARIA to enhance SVG accessibility.

Custom Colors

Like other default themes, this one comes with some color options so you can make the theme your own. Twenty Seventeen uses saturation to create a custom color scheme that will look great. That saturation level can be adjusted, like so:

function childtheme_custom_colors_saturation() {
	return 25;
add_filter( 'twentyseventeen_custom_colors_saturation', 'childtheme_custom_colors_saturation' );

So the lower the number there, the more muted a color appears, and the higher it is, the more intense a color becomes.

You can also add new CSS to the existing CSS output for custom colors.

By adding a filter, child themes can add additional selectors onto the custom color scheme CSS. Like so:

// Add child theme selectors for color schemes.
function dynamic_seventeen_custom_colors_css( $css, $hue, $saturation ) {
	$css .= '
	.colors-custom .content-menu > article:not(.has-post-thumbnail),
	.colors-custom .content-menu > section:not(.has-post-thumbnail) {
		border-top-color: hsl( ' . $hue . ', ' . $saturation . ', 87% ); /* base: #ddd; */
	return $css;
add_filter( 'twentyseventeen_custom_colors_css', 'dynamic_seventeen_custom_colors_css', 10, 3 );

Enjoy customizing Twenty Seventeen and happy theming!

#4-7, #bundled-theme, #dev-notes, #twenty-seventeen