# Dynamic inputs for project map routing

> Use dynamic path segments, query strings, and locale nodes to create flexible routing with project maps.

Source: https://docs.uniform.app/docs/guides/composition/url-management/routing/dynamic-inputs

Dynamic inputs enable flexible, data-driven routing by allowing you to capture values from URLs and pass them to compositions. This includes dynamic path segments (like product IDs), query strings (like search parameters), and locale nodes for internationalization.

## What are dynamic inputs?

Dynamic inputs are values captured from the URL that are passed to compositions attached to project map nodes. These values can be used to:

- Fetch specific content from external systems based on URL parameters
- Apply conditional logic to show/hide components or change values
- Create reusable compositions that adapt to different URL patterns
- Support internationalized routing with locale-specific URLs

There are three types of dynamic inputs:

1. [**Dynamic path segments**](#dynamic-path-segments): Capture variable parts of the URL path (e.g., `/products/:productId`)
2. [**Query strings**](#query-strings): Capture URL query parameters (e.g., `?region=us-west&customerType=premium`)
3. [**Locale nodes**](#locale-nodes-and-localized-routes): Special dynamic segments that represent locale codes for internationalization

## Dynamic path segments

Dynamic path segments allow project map to resolve any value for one segment in a URL. Given a dynamic node path such as `/:lang/products/:productId`, this would resolve to the `:productId` project map node for values such as `/en/products/32` and `/uk/products/awesome`.

Once the route is matched, the specific dynamic values are [passed to the composition and resolve to external data](https://docs.uniform.app/docs/guides/composition/connect-external-data/dynamic-compositions).

### Configure a dynamic path segment

1. Navigate to **Experience > Project Map** and add a node by either clicking the **Add node** button, the  within your project map, or the  within your project map and select an option to add a node.
2. Select **Dynamic** under "Path segment" to create a dynamic path.
3. Enter a name for the dynamic segment (e.g., `productId`, `slug`, `category`).
4. Configure the attached composition and other node settings.
5. Save the node.

![Configuring a dynamic path segment](https://docs.uniform.app/images/guides/project-map/add-node-dynamic.png)

### Use dynamic path segments in compositions

Dynamic path segments are available as dynamic inputs in compositions attached to the node. You can use them to:

- Connect to [data resource variables](https://docs.uniform.app/docs/guides/composition/connect-external-data/data-resources#dynamic-inputs-with-data-resources) to fetch specific content
- Use in [conditional logic](https://docs.uniform.app/docs/guides/composition/conditional-logic) to show/hide components or change values
- Preview different values in the visual editor

Learn how to [create compositions for dynamic routes](https://docs.uniform.app/docs/guides/composition/connect-external-data/dynamic-compositions).

## Query strings

Query strings (also called query parameters) enable specific [query string](https://en.wikipedia.org/wiki/Query_string) values to be collected from the URL and passed to the Route API to be made available to compositions. These are useful for tasks such as regional targeting, customer segmentation, campaign tracking, and other cases where a path might have more than one value.

When you define a query string, you specify that it is an **allowed query string parameter** for the Route API. It is not required to be present in the URL, but if it is, it will be passed to the composition as a dynamic input. Any other query strings will be ignored by the Route API.

Query strings can be defined in two ways:

### Global query strings

Global query strings are configured once at the project map level in **Settings > Project Map** and are allowed on every route in the project map. The Route API accepts them and the edge cache treats them as allowed parameters, whether or not a given page uses them. Use these for parameters that stay consistent across your site (e.g., `utm_campaign`, `utm_source`, `region`, `customerType`, or a bounded A/B parameter such as `experimentVariant`).

**Benefits:**

- Configure once, allowed on every route
- Can be used in [component and composition patterns](https://docs.uniform.app/docs/guides/patterns#using-dynamic-inputs-in-patterns) for conditional logic and data resources
- Ensure consistency in query string naming, default values and predefined options across your project

> **Note:**
>
> Don't use high-cardinality values (for example visitor IDs) as allowed query strings. Every allowed query string widens the edge cache key for every route it matches.

> **Note:**
>
> If a query string is set up globally at the project level, you can't add another query string with the same name to individual nodes. In case of a conflict, the global query string is used.

[Learn how to configure global query strings](https://docs.uniform.app/docs/guides/project-maps#configure-global-query-strings).

#### Always show in the editor

Being allowed on a route and being visible in Canvas are two separate things. The **Always show in the editor** setting controls only the second one: what Canvas lists for authors, which is the preview chips, [visibility rules](https://docs.uniform.app/docs/guides/composition/conditional-logic/component-visibility-control), [conditional values](https://docs.uniform.app/docs/guides/composition/conditional-logic/conditional-values), and the **Add query string** menu.

| Setting | What authors see |
| --- | --- |
| **On** (default) | The query string appears on every composition and pattern. This is the setting every existing global query string has. |
| **Off** (opt-in) | Canvas hides the query string unless a composition, component pattern, or composition pattern opts in. |

A site can accumulate a lot of experiment and campaign parameters, and a project where all of them are always visible makes every composition noisy. Opt-in keeps one centrally governed global that an architect manages on the project map, while patterns and compositions reference that name only where it's relevant.

> **Opt-in changes the editor, not the route:**
>
> A URL such as `?experimentVariant=b` is still accepted on every route, including pages that never opted in. Marking a global query string as opt-in doesn't change the Route API or shrink the edge cache allowlist.

Existing global query strings stay always-visible until someone turns the setting off, so nothing changes in your project until you do.

#### Opt in on a pattern or composition

Opting in makes an existing opt-in global visible on one document. It never creates a query string: if a document opts into a name that isn't a global query string, Uniform ignores it. The name is neither created nor allowed.

1. [Create the global query string](https://docs.uniform.app/docs/guides/project-maps#configure-global-query-strings) and turn **Always show in the editor** off.
2. Open the component pattern, composition pattern, or composition.
3. Open **Properties** and find **Allowed Query Strings**.
4. Click **Add query string** and choose the opt-in global.
5. Save the composition or pattern.

On a pattern, the caption explains that anything using the pattern opts in automatically. You can pre-configure visibility rules and conditional values on the pattern itself — for example, show a promotional banner only when `experimentVariant` is `b`.

![The Properties panel of a component pattern, with experimentVariant added as an opt-in and utm_source shown with a from global chip.](https://docs.uniform.app/images/guides/patterns/pattern-allowed-query-strings.png)

On a composition that uses that pattern, the same query string appears with a **from pattern** chip. It isn't removable on the composition while the pattern is still there. Always-visible globals show a **from global** chip and can't be removed either.

![The Properties panel of a composition, showing experimentVariant with a from pattern chip and utm_source with a from global chip.](https://docs.uniform.app/images/guides/project-map/composition-allowed-query-strings.png)

A composition can also opt in directly, without a pattern, from the same **Add query string** menu. That row has a **Remove** action.

> **Note:**
>
> Don't add the same name as a [node-specific query string](#node-specific-query-strings) — the node editor rejects names that already exist globally.
>
> [Entry patterns](https://docs.uniform.app/docs/guides/patterns/entry-patterns) and [composition defaults](https://docs.uniform.app/docs/guides/patterns/composition-patterns#composition-patterns-vs-composition-defaults) can't opt into query strings. Node pickers and other non-composition surfaces still see every global query string.

#### Inherit, unlink, and paste opt-ins

Opt-ins travel with the pattern that declares them:

- Adding an opted-in [component pattern](https://docs.uniform.app/docs/guides/patterns/component-patterns) to a page, or creating a composition from an opted-in [composition pattern](https://docs.uniform.app/docs/guides/patterns/composition-patterns), surfaces the query string on that page with a **from pattern** chip.
- [Unlinking a component pattern](https://docs.uniform.app/docs/guides/patterns/component-patterns#unlink-component-patterns) copies the pattern's opt-ins onto the composition as direct opt-ins, so visibility rules on the local copy keep resolving. The unlink dialog says so before you confirm. Afterwards you can **Remove** the names from **Properties** if you no longer need them. A composition pattern page root has no unlink control — only **Edit composition pattern**.
- [Converting a component to a component pattern](https://docs.uniform.app/docs/guides/patterns/component-patterns#create-component-pattern) doesn't carry opt-ins into the new pattern, because they belong to the composition root rather than the component being extracted — opt in again from the new pattern's **Properties** so that visibility rules extracted along with it keep resolving wherever else the pattern is used.
- Copying a component pattern instance to the clipboard doesn't copy the source page's opt-ins. Pasting the pattern onto another composition re-resolves the pattern and inherits its opt-ins again.
- Creating another composition from the same composition pattern also re-resolves that pattern's opt-ins.

If you delete or rename the global query string, leftover opt-in names show an **orphan** chip and do nothing until you restore the global or remove the name.

#### Preview and visibility with opt-in globals

Opt-in globals appear in preview chips and [dynamic preview values](https://docs.uniform.app/docs/guides/composition/visual-editing#preview-dynamic-values) only after the composition, or a pattern it uses, has opted in. Always-visible globals appear on every composition.

Once a name is in effect on a document, visibility rules and conditional values that use it behave like any other dynamic input.

### Node-specific query strings

Node-specific query strings are set up individually on project map nodes for cases where a query string is needed only for a particular route. You can add node-specific query strings while [managing your project map nodes](https://docs.uniform.app/docs/guides/project-maps#add-nodes-to-a-project-map).

### Predefined options

You can define **predefined options** for both global and node-specific query strings. This lets you present authors with a dropdown menu listing the allowed values when [previewing in the visual editor](https://docs.uniform.app/docs/guides/composition/visual-editing#preview-dynamic-values). Authors must pick from these options instead of typing values manually.

![The Add Query String drawer for region, with two predefined options mapping North America to na and Europe to eu.](https://docs.uniform.app/images/guides/project-map/global-query-string-add.png)

> **Default values vs preview values:**
>
> Query strings have a _default value_ which is used when the query parameter isn't passed in the URL. This is different from the _preview value_ of a dynamic path segment that only applies when previewing the composition in the visual editor.

## Locale nodes

Locale nodes are special dynamic path segments that capture the locale code from the URL. They enable internationalized routing by allowing a single dynamic segment to represent any configured [locale](https://docs.uniform.app/docs/guides/composition/localization#locales).

For example, a locale node at `/:locale` in your project map will match `/en-US`, `/de-DE`, `/fr-FR`, etc., and pass the locale value to compositions as a dynamic input.

### How locale nodes work

Locale nodes are a specialized type of dynamic path segment configured in the project map. When the Route API resolves a URL with a locale node:

1. The locale value is extracted from the URL path
2. The locale is validated against your project's configured locales
3. The locale is passed to the composition and used for [locale resolution](https://docs.uniform.app/docs/guides/composition/localization#use-a-project-map-node-as-the-locale-resolver-recommended)
4. The composition is returned in the requested locale if available

### Configure locale nodes

To configure a locale node:

1. Navigate to **Experience > Project Map** and add a node
2. Select **Locale** under "Path segment"
3. Configure the attached composition and other node settings
4. Save the node

Learn more about [using locale nodes for locale resolution](https://docs.uniform.app/docs/guides/composition/localization#use-a-project-map-node-as-the-locale-resolver-recommended) in the localization guide.

## Using dynamic inputs with compositions

Dynamic inputs can be used in several ways within compositions:

### Connect to data resources

Use dynamic inputs to fetch specific content from external systems by [connecting them to data resource variables](https://docs.uniform.app/docs/guides/composition/connect-external-data/data-resources#dynamic-inputs-with-data-resources). For example, use a `productId` path segment to fetch product data, or a `q` query string to perform a search.

### Apply conditional logic

Use dynamic inputs in [conditional logic](https://docs.uniform.app/docs/guides/composition/conditional-logic) to:

- [Show or hide components](https://docs.uniform.app/docs/guides/composition/conditional-logic/component-visibility-control) based on query string values
- [Change parameter values](https://docs.uniform.app/docs/guides/composition/conditional-logic/conditional-values) based on dynamic input criteria

> **Using dynamic inputs in patterns:**
>
> [Global query strings](https://docs.uniform.app/docs/guides/composition/url-management/routing/dynamic-inputs#global-query-strings) can be leveraged within [component and composition patterns](https://docs.uniform.app/docs/guides/patterns#using-dynamic-inputs-in-patterns) to drive conditional logic and provide data to data resources. By doing so, you increase the reusability and flexibility of patterns, allowing them to adapt dynamically based on URL parameters.