Skip to main content
OpenURLAction(callback: (url: string) => OpenURLActionResult | void): Component;
​
callback
(url: string) => OpenURLActionResult | void
required
A function that receives a URL string and returns a result indicating how the URL should be handled. Returning void is treated the same as { systemAction: true }.

​
Returns

A Component value that is passed to .environment("openURL", ...) to intercept URL requests in the subtree.

​
Result Types

The callback can return one of these OpenURLActionResult values:
​
{ handled: true }
object
The URL was handled by your custom logic. No further action is taken.
​
{ discarded: true }
object
The URL should be ignored entirely.
​
{ systemAction: true }
object
Delegate to the platform’s default URL handler.
​
{ systemAction: { url, preferInApp? } }
object
Open a (possibly rewritten) URL. Set preferInApp to true to suggest an in-app browser.

​
Usage

​
Custom scheme handling

const body = () => {
    const navigate = useNavigate()

    return VStack([
        Markdown(props.content)
    ]).environment("openURL", OpenURLAction((url) => {
        if (url.startsWith("myapp://")) {
            navigate({ to: "deep-link", props: { url } })
            return { handled: true }
        }
        return { systemAction: true }
    }))
}

​
Open external URLs in-app

const body = () => {
    return VStack([
        Markdown(props.content)
    ]).environment("openURL", OpenURLAction((url) => {
        return {
            systemAction: {
                url,
                preferInApp: true
            }
        }
    }))
}

​
Block certain domains

const body = () => {
    return VStack([
        Markdown(props.content)
    ]).environment("openURL", OpenURLAction((url) => {
        if (url.includes("blocked-site.com")) {
            return { discarded: true }
        }
        return { systemAction: true }
    }))
}

​
URL rewriting

const body = () => {
    return VStack([
        Markdown(props.content)
    ]).environment("openURL", OpenURLAction((url) => {
        if (url.startsWith("http://")) {
            return {
                systemAction: {
                    url: url.replace("http://", "https://"),
                    preferInApp: true
                }
            }
        }
        return { systemAction: true }
    }))
}

​
Notes

  • The action is set via .environment("openURL", ...) and applies to all child components in the subtree.
  • Returning void (no return value) is treated the same as { systemAction: true }.
  • The preferInApp option is a hint to the platform. Not all platforms support in-app browsers.
  • The callback is synchronous. Use state updates or actions for async side effects.
  • URL validation is your responsibility — the system does not validate URLs before calling your handler.

​
See Also