# Component Visibility (Private Beta)

> Source: https://agilitycms.com/docs/developers/component-visibility

> [!NOTE]
> **Private beta.** Component visibility is available only on instances taking part in the beta, and it may change before it's released to everyone. If you'd like to join the beta, contact your Customer Success Manager or Agility Support.

Component visibility lets you decide, for each component model, **who can add it to a page** and **where it can go**. Use it to keep a page's structure the way you designed it: a hero component that only goes in the hero zone, a component only your design team should place, or a component that belongs to one site and not another. You can also **disable** a component so nobody can add it, without deleting the model or touching the pages that already use it.

## What it affects, and what it doesn't

Visibility rules only apply when a component is **placed**:

- adding a component to a zone
- moving a component to a different zone, or onto a different page model
- copying a component to a page

A component that's **already on a page** is never affected. It keeps rendering on your site, and editors can keep editing it, reordering it within its zone, and removing it. A rule only stops a new placement, so adding a rule never breaks an existing page, and re-saving a page that already holds a component the rule wouldn't allow still works.

Nothing changes on an instance until someone sets a rule. A component with no rules can be added by anyone who can edit the page, anywhere, just as before.

## Set a component's visibility

1. Go to **Models** → **Component Models** and open the component model.
2. In the right-hand rail, choose **Visibility**.
3. Set **Who can add this component**, **Sitemaps**, and **Page models and zones** (each is described below).
4. Save.

Administrators, Managers and Designers can change visibility. The component models list shows a **Visibility** column, so you can see at a glance which components are **Disabled** or **Restricted**, and hover for a summary of each rule.

## Who can add this component

| Option | What it means |
| --- | --- |
| **Anyone who can edit the page** | The default. Anyone who can edit the page can add the component. |
| **Only these people** | Only the people you choose can add it. Choose any of **Designers**, **Managers**, specific **Users** and specific **Teams**. **Administrators** are always included. |
| **Nobody (disabled)** | Nobody can add or copy the component, Administrators included, and it's hidden from the component list. See [Disable a component](#Disable-a-component). |

**Designers** and **Managers** mean anyone who holds that permission, whatever their role is called on your instance. Someone who belongs to a chosen team can add the component, including when the team gives them their access to the instance.

## Where it can go

Two settings control where a component can be placed. A component must match **both**.

**Sitemaps.** Choose **All sitemaps**, or **Only these sitemaps** and pick them. A page belongs to the sitemap at the top of its page tree.

**Page models and zones.** Choose **Anywhere**, or **Only these page models and zones**. Pick a page model to allow all of its zones, or pick only the zones you want. For example, to keep a hero component in the hero zone, pick just the **Hero** zone of each page model that has one.

The "where" rules apply to everyone, Administrators included, because they're about the page's structure, not about who's editing it.

If a sitemap, page model or zone you picked is later deleted, the rule shows it as **(deleted)**. A deleted target never matches. If every target in a list has been deleted, the component can't be placed anywhere until you update the rule.

## Disable a component

Choose **Nobody (disabled)** under **Who can add this component** to retire a component without deleting it. This is useful when several instances share the same models (for example, when you sync them with the CLI) and a component doesn't apply to one of them.

When a component is disabled:

- nobody can add it or copy it, Administrators included;
- it's hidden from the component list in the page editor;
- components already on a page still render and stay editable, and they can still be moved to another zone or page model, as long as the "who" and "where" rules allow it.

To use it again, choose **Anyone who can edit the page** or **Only these people**.

## What editors see

The page editor only offers what a rule allows:

- the component list only shows the components this person can add on this page;
- when adding a component, **Choose Zone** only lists the zones it's allowed in;
- a zone the component can't go in won't accept it when it's dragged there;
- **Copy Component** only offers the zones of the target page that the component is allowed in;
- when you change a page's page model, each component moves to the first zone of the new page model that it's allowed in. If a component isn't allowed in any of them, the change is stopped and Agility lists the components that are in the way.

If a placement is refused, the message says why, using one of these sentences:

- *The "Hero" component is disabled on this instance.*
- *You don't have permission to add the "Hero" component.*
- *The "Hero" component isn't allowed on the "Main" sitemap.*
- *The "Hero" component isn't allowed in the "Main Content" zone of the "Landing Page" page model.*

For the editor's view of this, see [Why can't I add a component?](/docs/editors/component-visibility).

## The Management API, MCP and CLI

The same rules are checked on the server, so they apply however a page is saved: the Manager App, the Management API, the Management SDK, the MCP server and the Agility CLI.

- **Saving a page.** A page save that places a component the rules don't allow is refused with a **400**, and the message is one of the sentences above. The whole save is refused, so none of that save's other changes to the page are kept. As in the Manager App, a placement that's already on the page is never re-checked. The check is made as the user the token belongs to, so a script running with a non-Administrator's Personal Access Token can be refused by a "who" rule.
- **Reading and setting rules.** The Management API has three endpoints, documented in the [API reference](https://mgmt.aglty.io/index.html):
  - `GET /api/v1/instance/{guid}/model/availability` returns the rules of every component model that has any.
  - `GET /api/v1/instance/{guid}/model/{id}/availability` returns one component model's rules. A null `addableBy` means anyone who can edit the page, and a null `allowedIn` means anywhere.
  - `POST /api/v1/instance/{guid}/model/{id}/availability` saves them. `addableBy` and `allowedIn` are saved separately: leave a group out (or send `null`) to keep it, send an object to replace it, or send one whose lists are all empty to remove the restriction. Users, teams, sitemaps, page models and zones are matched by ID, or by email address or name when the ID isn't found, so a rule can be copied between instances. If any target can't be matched, nothing is saved and the 400 lists them.

  Anyone on the instance can read the rules. Saving them needs the same permission as saving a model.
- **Disabling a component** is done in the Visibility pane. Through the Management API, a model's `isVisible` setting only applies when the model is created; saving an existing model never changes it.

### Syncing instances with the CLI

Visibility settings belong to each instance:

- **Who and where rules are never copied** by `agility sync`. Set them on each instance.
- **Disabled is copied only when the sync creates the model** on the target instance. After that, each instance keeps its own setting, so a component you disable on one instance stays disabled through every later sync.
- If the sync can't save a page because of a visibility rule on the target (for example, a new page that uses a component the target has disabled), that page is skipped and the reason is shown in the sync summary. The sync carries on with the other pages. The page is tried again on the next sync, so change the rule, the model or the source page to let it through.

## Good to know

- Visibility controls placement only. It doesn't hide a component's content on your website, and it doesn't stop anyone from editing a component that's already on a page.
- Rules apply to **component models**. Content models and page models aren't covered yet.
- A change to a rule can take a couple of minutes to show up in a page editor that's already open.

## Related

- [Component Models](/docs/developers/component-models)
- [Page Models](/docs/developers/page-models)
- [User Permissions](/docs/owners-admins/user-permissions)
- [Why can't I add a component?](/docs/editors/component-visibility)

---

## Related pages

- [Content-first Approach](https://agilitycms.com/docs/developers/content-first.md)
- [Content Models](https://agilitycms.com/docs/developers/content-models.md)
- [Component Models ](https://agilitycms.com/docs/developers/component-models.md)
- [Fields](https://agilitycms.com/docs/developers/fields.md)
- [Nest, Link or Share? Choosing Linked Content Field Types](https://agilitycms.com/docs/developers/linked-content-field-types.md)
- [Getting Started with Linked Content](https://agilitycms.com/docs/developers/getting-started-with-linked-content.md)
- [Sitemaps](https://agilitycms.com/docs/developers/sitemaps.md)
- [Page Models](https://agilitycms.com/docs/developers/page-models.md)
- [Setting Up Preview](https://agilitycms.com/docs/developers/setting-up-preview.md)
- [Handling Agility URLs](https://agilitycms.com/docs/developers/handling-agility-urls.md)
- [Deployment & Code Repositories](https://agilitycms.com/docs/developers/deployment-code-repositories.md)
- [Tagging Content in Agility](https://agilitycms.com/docs/developers/tagging-content-in-agility.md)
- [Managing SEO for Developers](https://agilitycms.com/docs/developers/manging-seo-for-developers.md)
- [Mastering Nested Linked Content in Agility CMS: Enhance Hierarchical Data Management](https://agilitycms.com/docs/developers/nested-linked-content.md)
- [Advanced Field Validation with Regular Expressions](https://agilitycms.com/docs/developers/advanced-field-validation-with-regular-expressions.md)
- [Dynamic Content Control: Implementing Hide/When Formulas in Your Headless CMS Content Model](https://agilitycms.com/docs/developers/dynamic-content-control-implementing-hide-when-formulas-in-your-headless-cms-content-model.md)
- [Grouping Components into Tabs, Accordions, and Sections](https://agilitycms.com/docs/developers/grouping-components-into-tabs.md)
- [Conditional & Cross-Field Validation](https://agilitycms.com/docs/developers/conditional-and-cross-field-validation.md)
- [Set Up Web Studio with Any Framework](https://agilitycms.com/docs/developers/web-studio-setup-any-framework.md)
- [Troubleshooting Web Studio](https://agilitycms.com/docs/developers/troubleshooting-web-studio.md)
- [Content Modeling Anti-Patterns](https://agilitycms.com/docs/developers/content-modeling-anti-patterns.md)
- [Designing a Taxonomy That Scales](https://agilitycms.com/docs/developers/designing-a-taxonomy.md)
- [Map Your Design System to Component Models](https://agilitycms.com/docs/developers/design-system-to-component-models.md)
- [Structured Content Explained](https://agilitycms.com/docs/developers/structured-content-explained.md)
- [Beyond the Website: Apps, Kiosks, Email and In-App](https://agilitycms.com/docs/developers/beyond-the-website.md)
- [Make Your Content Model Agent-Friendly](https://agilitycms.com/docs/developers/agent-friendly-content-models.md)

Index of every docs page: https://agilitycms.com/docs/llms.txt