Step-by-Step Tutorial: Building Your First Custom Post Type in WordPress

[0242024-07-01 12:00:00Z < class_=”section-header” id=”section1″ /> (ignore) Let’s ignore taxonomies for now unless you need categories or tags for your custom post type. If you want categories or tags specific to this post type, register a custom taxonomy using register_taxonomy. That function works similarly to register_post_type but focuses on taxonomy features such as labels, hierarchical behavior, and rewrite slugs. You can attach the taxonomy to the post type by passing the post type name as the first argument.

For a simple portfolio, you might register a taxonomy called “category_portfolio” that behaves like a regular category but is limited to the custom post type. This allows you to group portfolio items separately from regular blog posts, making filtering and front‑end queries more efficient.

To register the taxonomy, add the following code after the post type registration:

add_action( ‘init’, ‘my_register_taxonomy’ );
function my_register_taxonomy() {
    register_taxonomy( ‘portfolio_category’, ‘my_portfolio’, [
        ‘label’ => ‘Portfolio Category’,
        ‘public’ => true,
  >        ‘hierarchical’ => true,
        ‘show_admin_column’ => true,
        ‘label’ => ‘Portfolio Category’,
        ‘show_in_rest’ => false
[/227]
[227]

After registering the taxonomy, you can assign posts to it from the edit screen, just like you would with a regular category. This makes it easier to group portfolio items and to query them on the front end using the built‑in query API.

If you need a custom taxonomy that works like tags, you can set hierarchical to false and register it as a tag‑like taxonomy. That gives you a flat list of keywords that can be used for filtering or tax‑based queries.

Registering a taxonomy is optional for a basic custom post type, but it becomes useful when you want to group items, filter them on the front end, or generate archive pages specific to the custom type.

Accessing the New Post Type

After registration, the new post type appears under the main admin menu, usually under a submenu called “Portfolio”. Open the dashboard, click the new label, and you will see a “Add New” button just like the standard post editor. The interface mirrors the regular post editor, so you can add a title, upload a featured image, and start writing content.

To view the new post type, navigate to the admin dashboard, locate the new menu item, and click “Portfolio”. From there you can add a new item, fill in the title, upload a featured image, and start publishing.

Step 4: Displaying Content on the Front End

By default the custom post type appears in the site’s main menu if you set show_in_menu to true. If you prefer a dedicated archive page, add a rewrite rule or create a dedicated template file in your theme. For a simple portfolio, you might add a page template that queries all my_portfolio items and loops through them. The default archive-my_portfolio.php file in most themes already handles this, but you can also create a custom template file named portfolio.php and use the WP_Query class to fetch only your custom post type.

To display a list of portfolio items on the front page, add the following line to your theme’s functions.php file:

add_filter( 'pre_get_posts', function( $query ) { if ( is_home() && ! is_admin ) { $args = array( 'post_type' => 'my_portfolio', 'posts_per_page' => -1 ); $query->set( $args ); } );

This code modifies the main query on the front page when it is not administrative, telling WordPress to load only my_portfolio posts. Adjust the arguments to suit your needs, such as limiting the number of items displayed.

Common Pitfalls and How to Avoid Them

One common mistake is forgetting to hook the registration function to init. If you call register_post_type directly without attaching it to init, WordPress will not register the type until the next request, which can cause confusion.

Another frequent issue is forgetting to flush rewrite rules after registering a new post type. After adding the registration code, visit the Permalinks page in the admin dashboard. This forces WordPress to rebuild its rewrite rules and makes the new post type accessible via URL.

Another pitfall is forgetting to add supports arguments. If you omit the supports array, the post type will lack essential UI elements such as the editor or featured images, making it difficult to manage content.

Finally, ensure that any custom rewrite slug you define does not clash with an existing slug. If you use the same slug as a built‑in post type, WordPress will not know which URL to serve and may return 404 errors.

Step 5: Accessing the New Post Type in the Admin

Once the registration code is in place and permalinks have been flushed, the new post type appears in the admin menu. It shows up as a top‑level item called “Portfolio”. Clicking “Add New” reveals the same meta boxes you see when creating a regular post: title field, editor, featured image, and optional custom fields.

To verify that the type works, open the dashboard, locate the new menu item, and click “Add New”. Fill in the title, add a featured image if desired, and start writing. The interface mirrors the standard post editor, so you should feel comfortable using it right away.

Step 5: Displaying Content on the Front End

With the registration complete and permalinks flushed, the new post type appears in the admin menu. Locate the new “Portfolio” item, click “Add New”, and you will have the same editing experience you use for regular posts. The interface is familiar, so you can start adding titles, uploading a featured image, and writing content right away.

To display the custom post type on the front page, modify the main query as shown below:

add_filter( 'pre_get_posts', function( $query ) { if ( is_home() && ! is_admin ) { $args = array( 'post_type' => 'my_portfolio', 'posts_per_page' => -1 ); $query->set( $args ); } );

Adjust the arguments to limit the number of items displayed, or to target a specific post type. For a simple portfolio you might use the default archive-my_portfolio.php file that already queries your custom post type, or you can create a dedicated template file named portfolio.php and use the WP_Query class to fetch only your custom post type.

[122]

If you prefer a dedicated template file, create a file named portfolio.php in your theme folder and add a custom query loop there. This gives you full control over the layout and allows you to add custom templates, taxonomies, or custom fields specific to the portfolio.

To test the setup, open the admin dashboard, locate the new “Portfolio” item in the menu, click “Add New”, and start adding content. The interface will feel familiar, so you can begin publishing right away.

Step 6: Displaying Content on the Front End

With the registration and permalink flush complete, the new post type appears as a top‑level item called “Portfolio” in the admin menu. Locate the new “Portfolio” item, click “Add New”, and start adding titles, a featured image, and content just like you would with a regular post.

To display the custom post type on the front page, modify the main query as shown below:

add_filter( 'pre_get_posts', function( $query ) { if ( is_home() && ! is_admin ) { $args = array( 'post_type' => 'my_portfolio', 'posts_per_page' => -1 ); $query->set( $args ); } );

[122]

Step 6: Displaying Content on the Front End

To display the custom post type on the front page, modify the main query as shown below:

add_filter( 'pre_get_posts', function( $query ) { if ( is_home() && ! is_admin ) { $args = array( 'post_type' => 'my_portfolio', 'posts_per_page' => -1 ); $query->set( $args ); } );

Common Pitfalls and How to Avoid Them

Another frequent issue is forgetting to add supports arguments. If you omit the supports array, the post type will lack essential UI elements such as the editor or featured images, making it difficult to manage content.

Another pitfall is forgetting to flush rewrite rules after registering a new post type. After adding the registration code, visit the Permalinks page in the admin dashboard. This forces WordPress to rebuild its rewrite rules and makes the new post type accessible via URL.

[p>Another pitfall is forgetting to flush rewrite rules after registering a new post type. After adding the registration code, visit the Permalinks page in the admin dashboard. This forces WordPress to rebuild its rewrite rules and makes the new post type accessible via URL.

[p>Another pitfall is forgetting to add supports arguments. If you omit the supports array, the post type will lack essential UI elements such as the editor or featured images, making it difficult to manage content.

[122]

[p>Another pitfall is forgetting to flush rewrite rules after registering a new post type. After adding the registration code, visit the

Accessing the New Post Type

Step 4: Displaying Content on the Front End

Common Pitfalls and How to Avoid Them

Step 5: Accessing the New Post Type in the Admin

Step 5: Displaying Content on the Front End

Step 6: Displaying Content on the Front End

Step 6: Displaying Content on the Front End

Common Pitfalls and How to Avoid Them

Leave a Reply Cancel reply