feat: add docs for the customHeadItems

yaroslav8765 · yaroslav8765 · commit 36c59ea95ad3 · 2025-07-28T17:03:44.000+03:00
diff --git a/adminforth/documentation/docs/tutorial/03-Customization/01-branding.md b/adminforth/documentation/docs/tutorial/03-Customization/01-branding.md
@@ -169,4 +169,37 @@ auth: {
 `loginBackgroundPosition` accepts values:
 
 - `over` - image will be over the whole login page with cover mode
-- `1/2`(default), `3/4`, `2/5`, `3/5` etc. - image will be in the left side of the login page with cover mode
+- `1/2`(default), `3/4`, `2/5`, `3/5` etc. - image will be in the left side of the login page with cover mode
+
+## Custom items in html head
+
+If you want to add custom elements to the HTML head, you can define them in the configuration:
+
+```ts title='./index.ts'
+customization: {
+  customHeadItems: [
+    {
+      tagName: 'link',
+      attributes: {
+        rel: 'stylesheet',
+        href: 'https://example.com/custom.css'
+      }
+    },
+    {
+      tagName: 'script',
+      attributes: {
+        src: 'https://example.com/custom.js',
+        defer: true
+      }
+    },
+    {
+      tagName: 'meta',
+      attributes: {
+        name: 'theme-color',
+        content: ' #000000'
+      }
+    }
+  ]
+}
+
+```
diff --git a/adminforth/modules/codeInjector.ts b/adminforth/modules/codeInjector.ts
@@ -547,7 +547,7 @@ class CodeInjector implements ICodeInjector {
     );
 
     // inject heads to index.html
-    const headItems = this.adminforth.config.customization!.customHeadItems;
+    const headItems = this.adminforth.config.customization?.customHeadItems;
     const renderedHead = headItems.map(({ tagName, attributes }) => {
       const attrs = Object.entries(attributes)
         .map(([k, v]) => `${k}="${v}"`)
diff --git a/adminforth/modules/restApi.ts b/adminforth/modules/restApi.ts
@@ -224,6 +224,7 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
           },
           rememberMeDays: this.adminforth.config.auth.rememberMeDays,
           singleTheme: this.adminforth.config.customization.singleTheme,
+          customHeadItems: this.adminforth.config.customization.customHeadItems,
         };
       },
     });
@@ -303,6 +304,7 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
           loginPageInjections: this.adminforth.config.customization.loginPageInjections,
           rememberMeDays: this.adminforth.config.auth.rememberMeDays,
           singleTheme: this.adminforth.config.customization.singleTheme,
+          customHeadItems: this.adminforth.config.customization.customHeadItems,
         }
 
         const loggedInPart = {
diff --git a/adminforth/spa/src/spa_types/core.ts b/adminforth/spa/src/spa_types/core.ts
@@ -40,6 +40,11 @@ export type CoreConfig = {
         show?: string,
         list?: string,
     } | string,
+
+    customHeadItems?: {
+        tagName: string;
+        attributes: { [key: string]: string | boolean };
+    }[],
 }
 
 
diff --git a/adminforth/types/Back.ts b/adminforth/types/Back.ts
@@ -765,6 +765,10 @@ interface AdminForthInputConfigCustomization {
     everyPageBottom?: AdminForthComponentDeclaration | Array<AdminForthComponentDeclaration>,
   }
 
+  /**
+  * Allows adding custom elements (e.g., <link>, <script>, <meta>) to the <head> of the HTML document.
+  * Each item must include a tag name and a set of attributes.
+  */
   customHeadItems?: {
     tagName: string;
     attributes: Record<string, string | boolean>;
diff --git a/adminforth/types/Common.ts b/adminforth/types/Common.ts
@@ -1081,7 +1081,11 @@ export interface AdminForthConfigForFrontend {
     header: Array<AdminForthComponentDeclarationFull>,
     sidebar: Array<AdminForthComponentDeclarationFull>,
     everyPageBottom: Array<AdminForthComponentDeclarationFull>,
-  }
+  },
+  customHeadItems?: {
+    tagName: string;
+    attributes: Record<string, string | boolean>;
+  }[],  
 }
 
 export interface GetBaseConfigResponse {
