From e00dcf785079988699ce870314f8d32ce379cad2 Mon Sep 17 00:00:00 2001
From: Mees Frensel <33722705+meesfrensel@users.noreply.github.com>
Date: Wed, 15 Jul 2026 19:32:05 +0200
Subject: [PATCH] fix(web): URI encode slug and reduce confusion for users
 (#29796)

Co-authored-by: bwees <brandonwees@gmail.com>
---
 i18n/en.json                                       |  5 +++--
 web/src/lib/components/SharedLinkFormFields.svelte |  7 +++++--
 web/src/lib/route.spec.ts                          | 14 ++++++++++++++
 web/src/lib/route.ts                               |  3 ++-
 web/src/lib/services/shared-link.service.ts        |  4 +---
 .../shared-links/(list)/[id]/edit/+page.svelte     |  6 ++++--
 6 files changed, 29 insertions(+), 10 deletions(-)

diff --git a/i18n/en.json b/i18n/en.json
index 7a3e719f6d..53d1e4a6b2 100644
--- a/i18n/en.json
+++ b/i18n/en.json
@@ -814,7 +814,6 @@
   "custom_date": "Custom date",
   "custom_locale": "Custom locale",
   "custom_locale_description": "Format dates, times, and numbers based on the selected language and region",
-  "custom_url": "Custom URL",
   "cutoff_date_description": "Keep photos from the last…",
   "cutoff_day": "{count, plural, one {day} other {days}}",
   "cutoff_year": "{count, plural, one {year} other {years}}",
@@ -1948,7 +1947,9 @@
   "shared_link_app_bar_title": "Shared Links",
   "shared_link_clipboard_copied_massage": "Copied to clipboard",
   "shared_link_create_error": "Error while creating shared link",
-  "shared_link_custom_url_description": "Access this shared link with a custom URL",
+  "shared_link_custom_url_description": "Access this shared link with a custom URL name",
+  "shared_link_custom_url_title": "Custom URL",
+  "shared_link_custom_url_warning": "Warning: a custom URL name with a forward slash may not behave as you expect.",
   "shared_link_edit_description_hint": "Enter the share description",
   "shared_link_edit_expire_after_option_day": "1 day",
   "shared_link_edit_expire_after_option_days": "{count} days",
diff --git a/web/src/lib/components/SharedLinkFormFields.svelte b/web/src/lib/components/SharedLinkFormFields.svelte
index cb371fd800..30067bcb9b 100644
--- a/web/src/lib/components/SharedLinkFormFields.svelte
+++ b/web/src/lib/components/SharedLinkFormFields.svelte
@@ -1,6 +1,6 @@
 <script lang="ts">
   import SharedLinkExpiration from '$lib/components/SharedLinkExpiration.svelte';
-  import { Field, Input, PasswordInput, Switch, Text } from '@immich/ui';
+  import { Field, HelperText, Input, PasswordInput, Switch, Text } from '@immich/ui';
   import { t } from 'svelte-i18n';
 
   type Props = {
@@ -32,8 +32,11 @@
 
 <div class="mt-4 flex flex-col gap-4">
   <div>
-    <Field label={$t('custom_url')} description={$t('shared_link_custom_url_description')}>
+    <Field label={$t('shared_link_custom_url_title')} description={$t('shared_link_custom_url_description')}>
       <Input bind:value={slug} autocomplete="off" />
+      {#if slug.includes('/')}
+        <HelperText class="text-warning">{$t('shared_link_custom_url_warning')}</HelperText>
+      {/if}
     </Field>
     {#if slug}
       <Text size="tiny" color="muted" class="pt-2 break-all">/s/{encodeURIComponent(slug)}</Text>
diff --git a/web/src/lib/route.spec.ts b/web/src/lib/route.spec.ts
index 30cc183f31..e00b2af8fb 100644
--- a/web/src/lib/route.spec.ts
+++ b/web/src/lib/route.spec.ts
@@ -24,6 +24,20 @@ describe('Route', () => {
     });
   });
 
+  describe(Route.viewSharedLink.name, () => {
+    it('should work with key', () => {
+      expect(Route.viewSharedLink({ key: 'uuid-key' })).toBe('/share/uuid-key');
+    });
+
+    it('should work with key and slug', () => {
+      expect(Route.viewSharedLink({ key: 'uuid-key', slug: 'custom-slug' })).toBe('/s/custom-slug');
+    });
+
+    it('should URI encode slug', () => {
+      expect(Route.viewSharedLink({ key: 'uuid-key', slug: 'albums/the-moon?' })).toBe('/s/albums%2Fthe-moon%3F');
+    });
+  });
+
   describe(Route.tags.name, () => {
     it('should work', () => {
       expect(Route.tags()).toBe('/tags');
diff --git a/web/src/lib/route.ts b/web/src/lib/route.ts
index 8542617ab1..49e51928f6 100644
--- a/web/src/lib/route.ts
+++ b/web/src/lib/route.ts
@@ -120,7 +120,8 @@ export const Route = {
   // shared links
   sharedLinks: (params?: { filter?: SharedLinkTab }) => '/shared-links' + asQueryString(params),
   editSharedLink: ({ id }: { id: string }) => `/shared-links/${id}/edit`,
-  viewSharedLink: ({ slug, key }: { slug?: string | null; key: string }) => (slug ? `/s/${slug}` : `/share/${key}`),
+  viewSharedLink: ({ slug, key }: { slug?: string | null; key: string }) =>
+    slug ? `/s/${encodeURIComponent(slug)}` : `/share/${key}`,
 
   // settings
   userSettings: (params?: { isOpen?: OpenQueryParam }) => '/user-settings' + asQueryString(params),
diff --git a/web/src/lib/services/shared-link.service.ts b/web/src/lib/services/shared-link.service.ts
index 69f90b28d5..3699c0ed75 100644
--- a/web/src/lib/services/shared-link.service.ts
+++ b/web/src/lib/services/shared-link.service.ts
@@ -60,9 +60,7 @@ export const getSharedLinkActions = ($t: MessageFormatter, sharedLink: SharedLin
 };
 
 export const asUrl = (sharedLink: SharedLinkResponseDto) => {
-  const path = sharedLink.slug
-    ? `s/${encodeURIComponent(sharedLink.slug)}`
-    : `share/${encodeURIComponent(sharedLink.key)}`;
+  const path = Route.viewSharedLink(sharedLink);
   return new URL(path, serverConfigManager.value.externalDomain || globalThis.location.origin).href;
 };
 
diff --git a/web/src/routes/(user)/shared-links/(list)/[id]/edit/+page.svelte b/web/src/routes/(user)/shared-links/(list)/[id]/edit/+page.svelte
index 0d91a50d1d..ac069ff084 100644
--- a/web/src/routes/(user)/shared-links/(list)/[id]/edit/+page.svelte
+++ b/web/src/routes/(user)/shared-links/(list)/[id]/edit/+page.svelte
@@ -56,8 +56,10 @@
 
   {#if shareType === SharedLinkType.Individual}
     <div class="text-sm">
-      {$t('individual_share')} |
-      <span class="text-primary">{sharedLink.description || ''}</span>
+      {$t('individual_share')}
+      {#if description !== ''}
+        | <span class="text-primary">{description}</span>
+      {/if}
     </div>
   {/if}