Introduction to Properties
This guide explains the new experience and shows how to get started quickly: create a property group, add it to a page, fill in values, and understand when to use the portal, byline, report, and display macro.
Properties helps teams capture structured information directly in Confluence. Instead of burying important details in page text, you can store them in reusable property groups with typed fields such as text, dates, people, links, and status-like selections.
Start here
Best for first-time users: start by creating one simple property group for a real use case, such as Project Info, Employee Profile, or Meeting Metadata. This makes the structure easier to understand than starting with too many fields at once.
Open the Properties experience from your page.
Create a property group.
Add the fields your team needs.
Attach that group to a Confluence page.
Fill in values from the page-level Properties panel.
Use reports or display macro when you want to surface the data elsewhere.
Create your first property group
The Property Groups Portal is the main place for setting up reusable structures. In the new design, the portal is organized into three clear areas so users can browse groups, build them, and choose field types more easily.
Editor area | Location | What it is used for | Typical actions |
|---|---|---|---|
Property Groups | Left | Browse and organize all available property groups | Create groups & switch between groups. |
Canvas | Middle | Build and configure the selected group | Add fields, review layout, update labels and settings |
Fields | Right | Choose field types | Select the right field for the type of data you want to collect |
When creating a new property group, give it a clear name that reflects the information it will hold. Good names are specific and reusable, for example Project Overview, Customer Details, or Release Metadata.
Labels
Labels are created directly during property group creation. If a user types any value in the Label field, that typed value becomes the category name and the property group is saved under it. If the user does not want to organize the group under a label, they simply don’t fill the label textbox.
Supported field types
Field type | Best used for | Example |
|---|---|---|
Text | Free-form written information | Project summary |
Select | One choice from a fixed list | Status |
Multiselect | Multiple choices from a list | Tags or regions |
People | Users in the workspace | Owner or reviewer |
Email addresses | Support contact | |
Phone | Phone numbers | Emergency contact |
Date | Dates or timestamps | Launch date |
Page | Links to Confluence pages | Related document |
URL | External links | Reference website |
Number | Numeric values | Budget or score |
Design tip: choose field types based on how the data should behave later. For example, use Select instead of Text when consistency matters, because reports and filtering work better when values are standardized.
Use properties on a page
On Confluence pages, properties are hidden by default and opened through the page-level Properties entry point. This keeps the page body clean while still making structured data easy to access.
Capability | How it works | Why it helps |
|---|---|---|
Open properties | Click the Properties entry point on the page | View metadata without changing page content |
Add property group | Select an existing group and attach it to the current page | Reuse the same structure across many pages |
Create new group | Open the editor from the page flow | Create a reusable structure when no suitable group exists yet |
Edit values | Update field values directly in context | Make quick changes without switching to a heavier setup flow |
Review changes | Open the field changelog | See who changed what and when |
This page-level panel is now the default working experience for most users. It is especially useful when the goal is to fill in or update values on a page that already has a property group attached.
Example: A team creates a property group called Project Overview with fields for Owner, Status, Start Date, Related Page, and Budget. They attach it to each project page. Contributors then open the Properties panel and fill in the values as the project evolves, while managers use the same structured fields later in reports.
Surface property data where readers need it
Not every reader will open the Properties panel. When important metadata should be visible inside the page body itself, use the Display Property Groups macro.
Display Property Groups macro
This macro lets users render selected property groups inline on the page, which is useful for pages that should show structured information directly in the content.
Entry point: add the macro from the Confluence macro picker by selecting Property Groups Display.
Selection: choose one or more property groups available for the current page or space.
Result: the chosen groups are rendered inline in the page body for easier reading.
Exports: the displayed groups are preserved in exports such as PDF or Word.
Important: the display macro is for showing existing property groups. It is not the place to create new groups or redesign field structure. Use the editor for setup and the page-level Properties panel for in-context value updates.
Report across pages
When the same property group is used on many pages, the Property Group Report becomes the best way to review that information at scale.
The redesigned report experience is intended to feel closer to a modern Atlassian-native table: easier to scan, easier to configure, and more reliable for larger datasets.
Structured overview: compare values from many pages in one place.
Column customization: decide which fields should be visible.
Filtering and sorting: narrow down results by relevant criteria.
Inline editing direction: support lighter, faster updates close to the data.
Use this when | Recommended feature |
|---|---|
You want to fill in or update values on one page | Properties byline |
You want key metadata visible inside the page content | Display Property Groups macro |
You want to compare the same structured data across many pages | Property Group Report |
Recommended guidance
Start small. Create one property group for one repeatable use case before scaling to multiple teams.
Use clear field names. Labels such as Owner, Status, and Due Date are easier to understand than overly technical names.
Prefer structured fields over free text when the data will later be filtered, reported on, or reused.
Use the byline Properties as the default editing experience for day-to-day page updates.
Use the display macro selectively when readers need to see metadata directly in the page body.
Use reports for scale when teams need an overview across many pages.