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.

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: Capture variable parts of the URL path (e.g., /products/:productId)
  2. Query strings: Capture URL query parameters (e.g., ?region=us-west&customerType=premium)
  3. Locale nodes: Special dynamic segments that represent locale codes for internationalization

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.

  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.
add-node-dynamic
Configuring a dynamic path segment

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

Learn how to create compositions for dynamic routes.

Query strings (also called query parameters) enable specific 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 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 for conditional logic and data resources
  • Ensure consistency in query string naming, default values and predefined options across your project

attention

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.

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, conditional values, and the Add query string menu.

SettingWhat 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.

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 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.
Allowed Query Strings on a component pattern after opting into experimentVariant.

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.
A composition inherits the pattern's opt-in and labels it with a from pattern chip.

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 — the node editor rejects names that already exist globally.

Entry patterns and composition defaults can't opt into query strings. Node pickers and other non-composition surfaces still see every global query string.

Opt-ins travel with the pattern that declares them:

  • Adding an opted-in component pattern to a page, or creating a composition from an opted-in composition pattern, surfaces the query string on that page with a from pattern chip.
  • Unlinking a component pattern 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 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.

Opt-in globals appear in preview chips and dynamic preview 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 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.

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. 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.
Global query string with predefined options

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 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.

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.

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
  4. The composition is returned in the requested locale if available

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 in the localization guide.

Dynamic inputs can be used in several ways within compositions:

Use dynamic inputs to fetch specific content from external systems by connecting them to data resource variables. For example, use a productId path segment to fetch product data, or a q query string to perform a search.

Use dynamic inputs in conditional logic to:

Using dynamic inputs in patterns

Global query strings can be leveraged within component and composition 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.

Last modified
Previous
Routing
Next
Routing with Next.js