> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usertour.io/llms.txt
> Use this file to discover all available pages before exploring further.

# URL pattern matching

> Learn how to use URL patterns to control when and where your content appears in your application

## Overview

URL pattern matching is a powerful feature in Usertour that helps you control exactly where your content appears. You can use it to:

* Auto-start onboarding flows or product tours
* Progress to the next step based on URL changes
* Mark checklist tasks as completed when users reach certain pages
* Control where specific content appears in your application

> **Note**: These URL pattern rules apply to **Current page** conditions only. For **Navigate to page** actions, you'll need to use the full URL and can insert user attributes for dynamic values.

## Quick Reference

Here are the key rules to remember:

* Only specify the URL parts you care about - omit the rest
* Use `-` as a wildcard to match anything
* Use `:segment` to match a single dynamic segment
* You can specify multiple patterns to include or exclude

## Common Patterns

### 1. Exact Path Matching

```html theme={null}
/app/dashboard
```

This matches any domain with exactly this path.

✅ Matches:

* `https://example.com/app/dashboard`
* `http://example.com/app/dashboard`
* `https://other-example.com/app/dashboard`

❌ Does not match:

* `https://example.com/app`
* `https://example.com/app/dashboard/sub`
* `https://example.com/app/dashboard/sub/page`

### 2. Including Subpaths

```html theme={null}
/app*
```

The `*` matches everything (including nothing).

✅ Matches:

* `https://example.com/app`
* `https://example.com/app/projects`
* `https://example.com/app/projects/1`
* `https://other-example.com/app`
* `https://example.com/applications`

❌ Does not match:

* `https://example.com/settings`

### 3. Only Subpaths

```html theme={null}
/app/*
```

Note the `/` before the `*`.

✅ Matches:

* `https://example.com/app/projects`
* `https://example.com/app/projects/1`
* `https://other-example.com/app/projects`

❌ Does not match:

* `https://example.com/app`
* `https://example.com/applications`

### 4. Dynamic Path Segments

```html theme={null}
/projects/:project/details
```

`:project` matches any single path segment (anything except `/`).

✅ Matches:

* `https://example.com/projects/1/details`
* `https://example.com/projects/2/details`

❌ Does not match:

* `https://example.com/projects/1/details/edit`
* `https://example.com/projects/1/history`

### 5. Mixing Dynamic Segments and Subpaths

```html theme={null}
/app/:company/projects/*
```

✅ Matches:

* `https://example.com/app/apple/projects/1`
* `https://example.com/app/banana/projects/1`
* `https://example.com/app/banana/projects/1/details`

❌ Does not match:

* `https://example.com/app/apple/projects`

### 6. Specific Domain

```html theme={null}
app.com
```

✅ Matches:

* `https://app.com/`
* `https://app.com/any/path`

❌ Does not match:

* `https://www.app.com/`
* `https://not-app.com/`

### 7. Dynamic Subdomain

```html theme={null}
:subdomain.app.com
```

✅ Matches:

* `https://www.app.com/`
* `https://www.app.com/any/path`
* `https://dashboard.app.com/`

❌ Does not match:

* `https://app.com/`
* `https://multiple.levels.app.com/`
* `https://www.not-app.com/`

### 8. Mix Domain and Path

```html theme={null}
:subdomain.example.com/app/:company/projects\*
```

✅ Matches:

* `https://dashboard.example.com/app/apple/projects`
* `https://dashboard.example.com/app/apple/projects/1`

## URL Structure

Let's break down a URL into its components:

```html theme={null}
https://my.app.com/acme-inc/dashboard?tab=analytics#charts
\___/   \________/\_________________/ \___________/ \____/
  |         |              |                |          |
scheme    domain          path            query     fragment
```

### Scheme

The part before `://` (usually `http` or `https`).

* Usually optional in patterns
* Only specify if you need to match a specific scheme

```html theme={null}
https://my.app.com/acme-inc/dashboard?tab=analytics#charts
\___/
  |
scheme
```

### Domain

The part between `://` and the first `/`.

```html theme={null}
https://my.app.com/acme-inc/dashboard?tab=analytics#charts
        \________/
            |
          domain
```

#### Dynamic Subdomains

To match dynamic subdomains (e.g. `apple.app.com` and `banana.app.com`), use a colon and an arbitrary name such as `:company.app.com`. `:company` will match a non-empty subdomain, meaning it will not include `.`. The name after `:` does not matter and is currently not used for anything.

`:company.app.com` and `:subdomain.app.com` are equivalent and will match:

* `apple.app.com`
* `banana.app.com`

They will not match:

* `app.com` (missing subdomain)
* `more.apple.app.com` (more subdomains)

#### Wildcard Domains

You can also use `*` as a wildcard character to match any number of subdomains.

`*.app.com` will match both `one.app.com` and `one.two.app.com`, but not `app.com`.

`*app.com` will match `app.com`, but will also match `myapp.com`.

### Path

In a URL, the path is the part that comes after the domain and before either the query parameters (starting with `?`) or the fragment (starting with `#`).

```html theme={null}
https://my.app.com/acme-inc/dashboard?tab=analytics#charts
                  \_________________/
                           |
                          path
```

#### Basic Rules

1. Paths **MUST** start with a forward slash `/`
2. If you omit the leading `/` (e.g. `app/projects`), the system will treat `app` as a domain
3. The correct pattern should be `/app/projects`

#### Dynamic Path Segments

Use `:paramName` to match dynamic path segments:

```js theme={null}
// Example: /app/:company/projects
// :company matches any non-empty string without /
```

✅ Will match:

* `/app/apple/projects`
* `/app/banana/projects`

❌ Won't match:

* `/app/projects` (missing company segment)
* `/app/apple/projects/1` (path too deep)

> **Tip**: Parameter names like `:company` or `:slug` are just identifiers - you can name them anything, they don't affect the matching logic

#### Wildcard Matching

Use `*` to match any path:

1. `/app/*`
   * ✅ Matches `/app/one`, `/app/one/two`
   * ❌ Does not match `/app`
   * Note: Requires at least one segment after `/app/`

2. `/app*`
   * ✅ Matches `/app`, `/applications`
   * Note: Matches anything that starts with `app`

3. `/*/projects`
   * ✅ Matches `/app/projects`, `/app/one/two/three/projects`
   * Note: Matches projects at any depth

#### Combining Patterns

You can mix dynamic segments and wildcards in the same pattern:

```js theme={null}
/*/customers/:customer/invoices/:invoice/*
```

This pattern will:

* Match any path at the start
* Capture a specific customer
* Capture a specific invoice
* Match any remaining path

### Query

The part that comes after `?` and before `#` in a URL.

```html theme={null}
https://my.app.com/acme-inc/dashboard?tab=analytics#charts
                                      \___________/
                                            |
                                          query
```

#### Basic Rules

* Query parameters are key-value pairs (e.g. `key=value`)
* Multiple parameters are separated by `&`
* Order doesn't matter
* Extra parameters are ignored
* Parameter values are optional

#### Examples

`?fruit=apple&tab=analytics` will match:

* `?fruit=apple&tab=analytics`
* `?tab=analytics&fruit=apple` (different order, same result)
* `?other=test&fruit=apple&tab=analytics` (extra params ignored)

#### Wildcard Matching

1. Match values starting with specific text:

```js theme={null}
// ?param=a* matches:
- ?param=apple
- ?param=admin
// But won't match:
- ?param=banana (doesn't start with 'a')
- ?param (no value)
- ?param2=apple (wrong parameter name)
```

2. Match any value:

```js theme={null}
// ?param=* matches:
- ?param=anything
- ?param (empty value is OK)
// But won't match:
- ?param2=value (wrong parameter)
```

### Fragment

The part that comes after `#` in a URL.

```html theme={null}
https://my.app.com/acme-inc/dashboard?tab=analytics#charts
                                                    \____/
                                                       |
                                                    fragment
```

#### Fragment Patterns

Fragments follow the same rules as paths:

1. Dynamic segments:

```js theme={null}
#/projects/:project/dashboard
```

2. Wildcards:

```js theme={null}
#/projects/:project/dashboard/*
```

> **Tip**: In single-page applications (SPAs), fragments often act like paths and can be matched using the same patterns