Explainers · Explainer
What Is a Custom Post Type? A Plain Explanation

Short answer
A custom post type is a content type you register yourself when the built-in types do not fit what you want to publish. You register it with the register_post_type function, hooked to the init action, and it gets its own admin screen and URLs. A shop's products are the classic example: WooCommerce registers a product post type for them.
Key takeaways
- A custom post type is a content type you register yourself when posts and pages do not fit.
- You register one with register_post_type, hooked to the init action, and flush the rewrite rules once.
- A post-type key must be 1 to 20 characters long and cannot start with wp_.
- Set show_in_rest to true or the type will not show in the block editor.
- Put custom post types in a plugin, not a theme, so the content stays when the theme changes.
What is a custom post type?
A custom post type is a content type you register yourself when the built-in types do not fit what you want to publish.
WordPress ships with posts and pages, but many sites need more kinds of content. A shop needs products, a course site needs lessons, and a review site needs movies. A custom post type gives each kind its own home in the admin area.
The Plugin Handbook on Developer.WordPress.org explains that once you register a custom post type, it gets its own top-level admin screen for managing and creating items of that type. The type also gets its own URLs on the front of the site.
What post types does WordPress include by default?
WordPress ships with five default post types: post, page, attachment, revision, and nav_menu_item.
The Plugin Handbook lists those five as the defaults. The function reference for register_post_type() gives a fuller list of seven built-ins, adding custom_css and customize_changeset for the Customizer. The reference also lists reserved types such as wp_block, wp_template, and wp_navigation that you must not reuse.
Custom post types sit beside these built-ins. They use the same posts table in the database, as Learn WordPress notes, and they behave like normal content once registered.
| Post type | Key | What it holds |
|---|---|---|
| Post | post | Blog posts and news |
| Page | page | Static pages |
| Attachment | attachment | Media library files |
| Revision | revision | Saved copies of posts and pages |
| Nav menu item | nav_menu_item | Menu links |
| Custom CSS | custom_css | Extra CSS from the Customizer |
| Custom post type | your own key | Products, events, books, and more |
How does a custom post type differ from a post or a page?
A custom post type differs from posts and pages only in purpose: it holds a different kind of content, with its own admin screen and URLs.
Posts are dated entries shown in reverse order, and pages are timeless, standalone content. A custom post type can act like either, depending on the settings you choose when you register it.
The clearest example is WooCommerce. WooCommerce's own docs show that it registers a product post type, with product_cat for categories and product_tag for tags.
Products live in the same wp_posts table as posts and pages, but they get their own admin screens and shop URLs. Our guide to posts vs pages in WordPress covers the built-in split in more detail.
How do you register a custom post type?
You register a custom post type with the register_post_type() function, hooked to the init action.
The function takes two parts: the post-type key, such as wporg_product, and an array of settings. The Plugin Handbook gives a short example that registers “Products” with public set to true and has_archive set to true, hooked with add_action( 'init', 'wporg_custom_post_type' ).
Three rules from the function reference matter here. First, the function dates back to WordPress 2.9.0, while custom post types as a full feature arrived with WordPress 3.0 “Thelonious” on 17 June 2010.
Second, you must not register a post type before the init action fires. Third, the function returns a WP_Post_Type object when it works, or a WP_Error when it fails.
After you register a type, you must flush the rewrite rules once so its URLs work. Do this on plugin activation, or on the after_switch_theme hook for themes.
Which settings matter most when you register one?
The settings that matter most are public, supports, has_archive, rewrite, and show_in_rest.
The table below sums up the key arguments and their defaults, from the function reference.
| Argument | Default | What it does |
|---|---|---|
public | false | Marks the type for public use in the admin and on the site |
has_archive | false | Gives the type an archive page |
rewrite | true | Sets the URL slug, using the key unless you give another slug |
supports | title, editor | Turns on title, editor, thumbnail, and other edit-screen features |
hierarchical | false | Makes the type act like pages, with parents and children |
menu_position | bottom of the menu | Sets where the admin menu item sits |
capability_type | post | Builds the read, edit, and delete permissions |
show_in_rest | false | Adds the type to the REST API and the block editor |
public sets the defaults for four other settings: exclude_from_search, publicly_queryable, show_ui, and show_in_nav_menus.
The supports list covers 11 core features: title, editor, comments, revisions, trackbacks, author, excerpt, page-attributes, thumbnail, custom-fields, and post-formats. Learn WordPress's book example uses title, editor, author, thumbnail, and excerpt, with show_in_rest set to true.
Where should the code live: in a plugin or a theme?
Put custom post types in a plugin, not a theme, so the content stays when the theme changes.
The Plugin Handbook gives this advice in plain words: put custom post types in a plugin rather than a theme, so user content stays portable even if the theme is changed.
If the type lives in a theme, it vanishes from the admin the moment a user switches themes, and the content becomes hard to reach.
The same advice applies to the rewrite rules. Flush them once when the plugin starts, or when the theme changes, and leave them alone after that. Our step-by-step guide to creating a custom post type in WordPress walks through the full setup.
What are taxonomies, and how do they fit in?
Taxonomies group custom post types, the way categories and tags group posts.
You create one with register_taxonomy(), which takes the taxonomy key, the post types it applies to, and its settings. The taxonomy reference caps the taxonomy key at 32 characters, using only lowercase letters, numbers, dashes, and underscores.
A taxonomy can be hierarchical, like categories, or flat, like tags. Hierarchical taxonomies show a checkbox list in the edit screen, while flat ones show a plain text field. WooCommerce uses both: product_cat groups products into categories, and product_tag works like tags.
Our guide to categories vs tags in WordPress explains the split in full.
One detail trips up many developers. When you register a post type, always list its taxonomies in the taxonomies argument, and still define each taxonomy with register_taxonomy(). Without both steps, the link is not picked up by query filters such as parse_query or pre_get_posts.
How do custom post types work with the block editor?
A custom post type works with the block editor when you set show_in_rest to true.
The show_in_rest setting adds the type to the REST API, and the block editor needs that to load. The setting arrived in WordPress 4.7.0, and two related settings followed later: rest_base defaults to the post-type key, and rest_namespace defaults to wp/v2 since WordPress 5.9.0.
The same rule applies to taxonomies. A taxonomy needs show_in_rest set to true before it shows up in the block editor. Without it, the type still works in the classic editor, but the block editor cannot list or edit its items.
What limits apply to post type names?
A post-type key must be 1 to 20 characters long, using only lowercase letters, numbers, dashes, and underscores.
The limit comes from the database: the post_type column is a VARCHAR(20). The function reference notes that WordPress returns a WP_Error with the code post_type_length_invalid when the key is too long, a check added in WordPress 4.2.0.
Two more rules apply. Do not start a key with wp_, since WordPress core uses that prefix. Do not pick a broad name such as product for your own type, because two types with the same key cannot both work.
Pick a clear prefix tied to your plugin or site, such as wporg_product in the handbook example.
How do you check a custom post type on your site?
Open the admin menu to see the type's screen, and visit its archive URL to see its public pages.
A registered type adds its own menu item, usually near the bottom of the admin menu unless menu_position moves it. Click it to list, add, and edit items of that type.
On the front of the site, the type gets its own URL slug by default. The handbook example uses example.com/wporg_product/%product_name%, and setting rewrite to a slug of products changes it to example.com/products/%product_name%.
If the archive page shows a 404 error after you register a type, flush the rewrite rules once, as the handbook describes, and check the slug again.
What mistakes should you avoid?
The most common mistakes are putting the type in a theme, skipping the rewrite flush, and picking a key that clashes with another type.
Watch for these:
- Registering the type in a theme, so it disappears when the theme changes.
- Forgetting to flush rewrite rules after registration, so archive pages return 404 errors.
- Reusing a reserved name such as
post,page,attachment,wp_block, orwp_template. - Using a key longer than 20 characters, or starting it with
wp_. - Leaving
show_in_restoff, so the type never shows in the block editor. - Registering too many types. Learn WordPress warns that registration runs on every site request, even on pages that never use the type, so each extra type adds load.
If you need extra fields on a type, our guide to adding custom fields in WordPress shows the options.
For layout control, see how to create a custom page template in WordPress.
Frequently asked questions
Is a custom post type the same as a post or a page?
Yes. WordPress ships with posts and pages, and a custom post type is a third kind of content that lives beside them in the same posts table. It gets its own admin screen and its own URLs, but it works like normal content once it is registered.
Should I register a custom post type in a theme or a plugin?
Put it in a plugin. The Plugin Handbook warns that a type registered in a theme disappears from the admin when the user switches themes, and the content becomes hard to reach. A plugin keeps the type and its content in place no matter which theme is active.
What limits apply to a custom post type name?
A post-type key must be 1 to 20 characters long, using only lowercase letters, numbers, dashes, and underscores. Do not start a key with wp_, and do not reuse a reserved name such as post, page, attachment, wp_block, or wp_template.
Why does my custom post type not show in the block editor?
Set show_in_rest to true when you register the type. This adds the type to the REST API, which the block editor needs to load. The same setting is needed on taxonomies before they show up in the block editor.
Why does my custom post type archive page show a 404 error?
Flush the rewrite rules once after you register the type, as the Plugin Handbook describes. The type's archive URL uses its key as the slug by default, so a 404 error usually means the rewrite rules were never flushed after registration.
Sources
- Registering Custom Post Types WordPress Developer Resources
- register_post_type() WordPress Developer Resources
- register_taxonomy() WordPress Developer Resources
- Custom post types Learn WordPress
- Installed Taxonomies and Post Types WooCommerce
- WordPress 3.0 “Thelonious” WordPress.org News
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.
Related guides
About the editors
Researched from the primary sources listed above and checked against our editorial rules before publishing.


