diff --git a/docs/troubleshooting/assets/20250430121220879251.png b/docs/troubleshooting/assets/20250430121220879251.png
new file mode 100644
index 00000000..74a91eef
Binary files /dev/null and b/docs/troubleshooting/assets/20250430121220879251.png differ
diff --git a/docs/troubleshooting/assets/20250430121221066642.png b/docs/troubleshooting/assets/20250430121221066642.png
new file mode 100644
index 00000000..aa4eca7b
Binary files /dev/null and b/docs/troubleshooting/assets/20250430121221066642.png differ
diff --git a/docs/troubleshooting/assets/20250430121248035007.png b/docs/troubleshooting/assets/20250430121248035007.png
new file mode 100644
index 00000000..b43dac23
Binary files /dev/null and b/docs/troubleshooting/assets/20250430121248035007.png differ
diff --git a/docs/troubleshooting/assets/20250430121248379992.png b/docs/troubleshooting/assets/20250430121248379992.png
new file mode 100644
index 00000000..1a62ee22
Binary files /dev/null and b/docs/troubleshooting/assets/20250430121248379992.png differ
diff --git a/docs/troubleshooting/assets/20250430121249048672.gif b/docs/troubleshooting/assets/20250430121249048672.gif
new file mode 100644
index 00000000..2cf8259a
Binary files /dev/null and b/docs/troubleshooting/assets/20250430121249048672.gif differ
diff --git a/docs/troubleshooting/assets/20250430121250214649.png b/docs/troubleshooting/assets/20250430121250214649.png
new file mode 100644
index 00000000..291efff1
Binary files /dev/null and b/docs/troubleshooting/assets/20250430121250214649.png differ
diff --git a/docs/troubleshooting/assets/20250430121250453056.png b/docs/troubleshooting/assets/20250430121250453056.png
new file mode 100644
index 00000000..13fd1cf1
Binary files /dev/null and b/docs/troubleshooting/assets/20250430121250453056.png differ
diff --git a/docs/troubleshooting/assets/20250430121252902305.png b/docs/troubleshooting/assets/20250430121252902305.png
new file mode 100644
index 00000000..4ffa4cc3
Binary files /dev/null and b/docs/troubleshooting/assets/20250430121252902305.png differ
diff --git a/docs/troubleshooting/assets/20250430121253238523.png b/docs/troubleshooting/assets/20250430121253238523.png
new file mode 100644
index 00000000..28ef0a15
Binary files /dev/null and b/docs/troubleshooting/assets/20250430121253238523.png differ
diff --git a/docs/troubleshooting/assets/20250430121322843622.gif b/docs/troubleshooting/assets/20250430121322843622.gif
new file mode 100644
index 00000000..3d10e257
Binary files /dev/null and b/docs/troubleshooting/assets/20250430121322843622.gif differ
diff --git a/docs/troubleshooting/assets/20250430121323364253.gif b/docs/troubleshooting/assets/20250430121323364253.gif
new file mode 100644
index 00000000..db231413
Binary files /dev/null and b/docs/troubleshooting/assets/20250430121323364253.gif differ
diff --git a/docs/troubleshooting/assets/20250430121324152439.png b/docs/troubleshooting/assets/20250430121324152439.png
new file mode 100644
index 00000000..56f993c5
Binary files /dev/null and b/docs/troubleshooting/assets/20250430121324152439.png differ
diff --git a/docs/troubleshooting/assets/20250430121324382074.png b/docs/troubleshooting/assets/20250430121324382074.png
new file mode 100644
index 00000000..c6b9079d
Binary files /dev/null and b/docs/troubleshooting/assets/20250430121324382074.png differ
diff --git a/docs/troubleshooting/assets/20250430121324695186.png b/docs/troubleshooting/assets/20250430121324695186.png
new file mode 100644
index 00000000..343d09f3
Binary files /dev/null and b/docs/troubleshooting/assets/20250430121324695186.png differ
diff --git a/docs/troubleshooting/assets/20250430121324981835.png b/docs/troubleshooting/assets/20250430121324981835.png
new file mode 100644
index 00000000..7a8c0feb
Binary files /dev/null and b/docs/troubleshooting/assets/20250430121324981835.png differ
diff --git a/docs/troubleshooting/assets/20250430121325311155.png b/docs/troubleshooting/assets/20250430121325311155.png
new file mode 100644
index 00000000..e9cb39ff
Binary files /dev/null and b/docs/troubleshooting/assets/20250430121325311155.png differ
diff --git a/docs/troubleshooting/assets/20250430121325659677.png b/docs/troubleshooting/assets/20250430121325659677.png
new file mode 100644
index 00000000..feb64565
Binary files /dev/null and b/docs/troubleshooting/assets/20250430121325659677.png differ
diff --git a/docs/troubleshooting/assets/20250430121325972589.png b/docs/troubleshooting/assets/20250430121325972589.png
new file mode 100644
index 00000000..470b2d65
Binary files /dev/null and b/docs/troubleshooting/assets/20250430121325972589.png differ
diff --git a/docs/troubleshooting/assets/20250430121326300880.png b/docs/troubleshooting/assets/20250430121326300880.png
new file mode 100644
index 00000000..b0f40e26
Binary files /dev/null and b/docs/troubleshooting/assets/20250430121326300880.png differ
diff --git a/docs/troubleshooting/assets/20250430121326628836.png b/docs/troubleshooting/assets/20250430121326628836.png
new file mode 100644
index 00000000..50a37b8b
Binary files /dev/null and b/docs/troubleshooting/assets/20250430121326628836.png differ
diff --git a/docs/troubleshooting/assets/20250430121459400158.png b/docs/troubleshooting/assets/20250430121459400158.png
new file mode 100644
index 00000000..3f73fc59
Binary files /dev/null and b/docs/troubleshooting/assets/20250430121459400158.png differ
diff --git a/docs/troubleshooting/assets/20250430121459696014.png b/docs/troubleshooting/assets/20250430121459696014.png
new file mode 100644
index 00000000..c7fea6dd
Binary files /dev/null and b/docs/troubleshooting/assets/20250430121459696014.png differ
diff --git a/docs/troubleshooting/assets/20250430121524709613.gif b/docs/troubleshooting/assets/20250430121524709613.gif
new file mode 100644
index 00000000..90042924
Binary files /dev/null and b/docs/troubleshooting/assets/20250430121524709613.gif differ
diff --git a/docs/troubleshooting/migrate-widget-issues/_category_.json b/docs/troubleshooting/migrate-widget-issues/_category_.json
new file mode 100644
index 00000000..cd298df5
--- /dev/null
+++ b/docs/troubleshooting/migrate-widget-issues/_category_.json
@@ -0,0 +1,3 @@
+{
+  "label": "Widget"
+}
\ No newline at end of file
diff --git a/docs/troubleshooting/migrate-widget-issues/configure_text_widget_auto_size_behavior.md b/docs/troubleshooting/migrate-widget-issues/configure_text_widget_auto_size_behavior.md
new file mode 100644
index 00000000..a26543ff
--- /dev/null
+++ b/docs/troubleshooting/migrate-widget-issues/configure_text_widget_auto_size_behavior.md
@@ -0,0 +1,48 @@
+---
+keywords: ['widget', 'auto size', 'text widget']
+slug: /configure-text-widget-auto-size-behavior
+title: Configure Text Widget Auto Size Behavior
+---
+
+# Configure Text Widget Auto Size Behavior
+
+The `Auto Size` option allows the `Text` widget to automatically reduce its font size to fit within its parent widget. This guide outlines the expected behavior and conditions required for this feature to function correctly.
+
+:::info[Prerequisites]
+- A `Text` widget has been added to the canvas.
+- The widget is placed inside a parent widget such as a `Container` or `Stack`.
+:::
+
+## Configure Parent Widget Dimensions
+
+  To enable `Auto Size`, the `Text` widget must be inside a widget that has both defined width and height. Without these constraints, the font size cannot be adjusted automatically.
+
+  1. Select the `Text` widget.
+  2. Check its parent widget.
+  3. Ensure both width and height are explicitly defined.
+
+  :::warning
+  Without defined dimensions, the `Auto Size` feature may not behave as expected.
+  :::
+
+  **Behavior Scenarios:**
+
+    The following examples illustrate how `Auto Size` behaves under different container configurations:
+
+      - Container with width set to `infinity` and height set to `100px`, `Auto Size` disabled. The text may overflow beyond the container.
+
+      - Container with width set to `infinity` and height set to `100px`, `Auto Size` enabled. The font size adjusts to fit the defined height.
+
+      - Container with width set to `30%` and no height defined, `Auto Size` enabled. The feature has no visible effect due to missing height constraint.
+
+      - Container with width set to `70%` and height set to `50px`, `Auto Size` enabled. The text is resized to the minimum allowed font size to remain within the container.
+
+        ![](../assets/20250430121459696014.png)
+
+  :::tip
+  Use `Auto Size` with percentage-based dimensions for better responsiveness. For example, set the container width to `30%` and enable `Auto Size` to allow the text size to adjust as the screen size changes.
+  :::
+
+  :::note
+  The `Auto Size` feature has a minimum font size threshold. If the container becomes too small, text may clip or overflow when resizing is no longer possible.
+  :::
\ No newline at end of file
diff --git a/docs/troubleshooting/migrate-widget-issues/custom_widget_errors.md b/docs/troubleshooting/migrate-widget-issues/custom_widget_errors.md
new file mode 100644
index 00000000..9be71fad
--- /dev/null
+++ b/docs/troubleshooting/migrate-widget-issues/custom_widget_errors.md
@@ -0,0 +1,90 @@
+---
+keywords: ['custom widget', 'widget errors', 'widget troubleshooting', 'flutterflow']
+slug: /custom-widget-errors
+title: Custom Widget Errors
+---
+
+# Custom Widget Errors
+
+This article demonstrates common errors and issues that may occur when creating a `Custom Widget` in FlutterFlow, along with steps to resolve them. In this example, an `Animated Text Widget` is used.
+
+![](../assets/20250430121322843622.gif)
+
+**Project URL:** [Animated Kit Widget Project](https://app.flutterflow.io/project/animated-kit-widget-fyqw6j)  
+
+**Run Mode URL:** [Animated Kit Widget Run Mode](https://app.flutterflow.io/run/QP62FwanUTRs7O3HJzdo)
+
+:::info[Prerequisites]
+- A custom widget has been added to your project.
+- Necessary packages have been added to **Custom Code > Packages**.
+:::
+
+:::tip[Best Practices Before Creating a Custom Widget]
+- Set a unique name for the custom widget in the left panel `Side Widget` field.
+- Start with the boilerplate code template provided by FlutterFlow. Copy it and modify your code from there.
+
+![](../assets/20250430121323364253.gif)
+:::
+
+
+**Common Errors and Solutions:**
+
+    - **Widget Name Conflicts with Package Name**
+
+        A common issue is using a widget name that conflicts with the name of an imported package.
+
+        Avoid generic or conflicting names like `main` or `widget`. Use unique widget names that do not overlap with package names.
+
+        ![](../assets/20250430121324152439.png)
+
+        ![](../assets/20250430121324382074.png)
+
+        Avoid using generic or conflicting names like `main` or `widget`. Always use unique widget names that do not overlap with any package names.
+
+    - **Missing Package Imports in Code**
+
+        After adding an external package as a dependency, you must import it at the top of your custom widget code. Failure to do so results in errors such as:
+
+        ```js
+        The method 'AnimatedText' isn't defined...
+        ```
+
+        ![](../assets/20250430121324695186.png)
+
+        Here is how to fix this issue:
+
+            - Visit the package page on **[pub.dev](https://pub.dev/)** and locate the import line in the package details section.
+            - Copy and paste the correct import statement into your custom widget code.
+
+                ![](../assets/20250430121324981835.png)  
+                ![](../assets/20250430121325311155.png)
+
+
+    - **Missing Indirect Dependencies**
+
+        Some packages may rely on additional external packages. Ensure that all required dependencies are also imported in your code.
+
+        ![](../assets/20250430121325659677.png)
+
+        In this example, the package depends on another package named `silver_tools`, which must also be imported. Always review the dependency chain for any external packages you add.
+
+        ![](../assets/20250430121325972589.png)
+
+        
+    - **Widget Name Mismatch Between UI and Code**
+
+        A mismatch between the widget name in FlutterFlow and the class name in your code will cause compilation errors.
+
+        Incorrect example:
+
+        ![](../assets/20250430121326300880.png)
+
+        Corrected version with matching names:
+
+        ![](../assets/20250430121326628836.png)
+
+        Ensure that the widget name matches exactly in both places.
+
+
+By following these best practices and carefully reviewing package imports, dependencies, and widget names, most common issues with `Custom Widgets` in FlutterFlow can be avoided.
+
diff --git a/docs/troubleshooting/migrate-widget-issues/emoji-size-on-ios-devices.md b/docs/troubleshooting/migrate-widget-issues/emoji-size-on-ios-devices.md
new file mode 100644
index 00000000..132bd116
--- /dev/null
+++ b/docs/troubleshooting/migrate-widget-issues/emoji-size-on-ios-devices.md
@@ -0,0 +1,42 @@
+---
+keywords: ['ios', 'emoji', 'text', 'size']
+slug: /emoji-size-on-ios-devices
+title: Emoji Size on iOS Devices
+---
+
+# Emoji Size on iOS Devices
+
+On iOS devices, emojis can appear oversized when rendered inside text widgets, disrupting the intended design and layout. This guide explains how to maintain consistent emoji sizing across all devices using container constraints and auto-sizing configuration.
+
+:::info[Prerequisites]
+- You are using a `Text` widget that includes emojis.
+- You are targeting iOS devices as part of your app deployment.
+:::
+
+## Steps to Maintain Consistent Emoji Size
+
+1. **Wrap the Text Widget in a Container**  
+   Create a `Container` with fixed width and height (example `32x32 pixels`) to restrict the emoji size.
+
+2. **Place the Emoji Inside a Text Widget**  
+   Add a `Text` widget containing the emoji and place it inside the container.
+
+3. **Set a Font Size**  
+   Apply a specific font size to the `Text` widget (example, `16`, `24`, etc.).
+
+4. **Enable Auto-Size**  
+   Turn on **Auto-Size** in the `Text` widget to allow responsive resizing within the fixed container.
+
+   ![](../assets/20250430121253238523.png)
+
+   This ensures that the emoji will resize according to the container's constraints and not exceed the intended bounds.
+
+   :::tip
+   Auto-Size works best when combined with fixed container dimensions. This approach prevents oversized emojis and supports responsive layouts.
+   :::
+
+   ![](../assets/20250430121252902305.png)
+
+:::info
+For more details and troubleshooting, see the **[official FlutterFlow guide on emoji rendering](https://intercom.help/flutterflow/en/articles/7044370-text-emoji-is-very-large-on-some-ios-devices)**.
+:::
diff --git a/docs/troubleshooting/migrate-widget-issues/infinite_scroll_pagination_in_listview.md b/docs/troubleshooting/migrate-widget-issues/infinite_scroll_pagination_in_listview.md
new file mode 100644
index 00000000..3acdbf04
--- /dev/null
+++ b/docs/troubleshooting/migrate-widget-issues/infinite_scroll_pagination_in_listview.md
@@ -0,0 +1,51 @@
+---
+keywords: ['listview', 'infinite scroll', 'pagination']
+slug: /infinite-scroll-pagination-in-listview
+title: Infinite Scroll Pagination in ListView
+---
+
+# Infinite Scroll Pagination in ListView
+
+If a `ListView` with **Infinite Scroll** enabled loads all items at once instead of paginating, the issue is typically related to layout configuration. This guide outlines how to correctly structure the widget for proper pagination behavior.
+
+:::info[Prerequisites]
+- Infinite Scroll is enabled in the `ListView`.
+- The widget is placed inside a layout that allows height constraints to be respected.
+:::
+
+Follow the steps below to configure ListView for pagination:
+
+1. **Ensure ListView Has a Defined Height**  
+   A `ListView` must have a height constraint to determine the viewport size and paginate correctly. Without a defined height, it will attempt to load all items.
+
+2. **Let ListView Handle Its Own Scrolling**  
+   - Disable scrolling in any parent `Column` or scrollable container.  
+   - Enable the **Primary** option, and wrap `ListView` in an `Expanded` widget.  
+   - This allows `ListView` to control scroll behavior and calculate items to load per page.
+
+      ![](../assets/20250430121248035007.png)
+
+3. **Wrap ListView Inside a Fixed-Height Container (if nested)**  
+   If `ListView` is inside a scrollable parent (like `Column` or `ListView`), wrap it in a `Container` with a defined height (e.g., `500px`). This ensures it doesn't expand indefinitely.
+
+      ![](../assets/20250430121248379992.png)
+
+4. **Avoid Missing Height Constraints**  
+   Without constraints, `ListView` will not know the visible size and will load all data at once, bypassing pagination.
+
+   :::warning
+   Placing `ListView` directly inside a scrollable parent without a defined height will break Infinite Scroll behavior.
+   :::
+
+5. **Use Layout Structure That Supports Scroll Isolation**  
+   Allow `ListView` to scroll independently before the parent scroll takes over. Combine this with defined height and `Expanded` usage for best results.
+
+      ![](../assets/20250430121249048672.gif)
+
+:::tip
+To optimize pagination, define consistent item heights and test using varying screen sizes.
+:::
+
+:::info[Additional Resources]
+- **[ListView Scroll Example Project](https://app.flutterflow.io/project/list-view-scroll-example-wdv076)** – View a working configuration example.
+:::
diff --git a/docs/troubleshooting/migrate-widget-issues/rive_animation_loading_errors.md b/docs/troubleshooting/migrate-widget-issues/rive_animation_loading_errors.md
new file mode 100644
index 00000000..ac6f1e31
--- /dev/null
+++ b/docs/troubleshooting/migrate-widget-issues/rive_animation_loading_errors.md
@@ -0,0 +1,33 @@
+---
+keywords: ['rive', 'animation', 'loading', 'error']
+slug: /rive-animation-loading-errors
+title: Rive Animation Loading Errors
+---
+
+# Rive Animation Loading Errors
+
+Rive animations may fail to render when the source file is incorrectly linked. This guide outlines how to provide a valid `.riv` file URL for successful animation loading.
+
+:::info[Prerequisites]
+- A valid Rive animation is hosted online with a `.riv` extension.
+- The animation is added to a FlutterFlow widget that supports Rive.
+:::
+
+## Steps to Fix Rive Animation Not Loading
+
+1. **Verify the Rive File URL**  
+   Ensure the file URL ends with `.riv` and points directly to a hosted Rive file.
+
+   ```text
+   https://public.rive.app/community/runtime-files/1199-2317-jack-olantern.riv
+    ```
+
+    If the URL points to a webpage or lacks the `.riv` extension, the animation will not load in FlutterFlow.
+
+2. **Copy the Correct Link from Rive Community:**
+
+    - Go to the animation page on the **[Rive Community](https://rive.app/community/)**.
+    - Right-click the **Download** button.
+    - Select Copy Link Address.
+
+        The copied link must end with `.riv`. Any URL that redirects to a webpage or file viewer will fail to render.
diff --git a/docs/troubleshooting/migrate-widget-issues/scroll_to_action_on_page_load.md b/docs/troubleshooting/migrate-widget-issues/scroll_to_action_on_page_load.md
new file mode 100644
index 00000000..34c4a1b1
--- /dev/null
+++ b/docs/troubleshooting/migrate-widget-issues/scroll_to_action_on_page_load.md
@@ -0,0 +1,37 @@
+---
+keywords: ['scroll to action', 'page load', 'delay', 'animation']
+slug: /scroll-to-action-on-page-load
+title: Scroll To Action on Page Load
+---
+
+# Scroll To Action on Page Load
+
+When a `Scroll To Action` fails to trigger during a page load, it is often because the scrollable widget has not fully rendered at the time the action executes. This guide outlines how to ensure the scroll action works reliably during page load.
+
+:::info[Prerequisites]
+- The `Scroll To Action` is configured inside an `On Page Load` action flow.
+- The target widget is inside a scrollable view such as `ListView` or `Column`.
+:::
+
+## Steps to Ensure Reliable Scroll Behavior:
+
+1. **Add a Delay Before the Scroll Action**  
+   Insert a `Delay Action` before the `Scroll To Action` to allow the widget tree to complete rendering. Recommended delay duration is 500 to 700 ms.
+
+   ![](../assets/20250430121250453056.png)
+
+2. **Use Load Animations for Scrollable Widgets**  
+   Applying an animation ensures the widget is fully visible before scrolling.
+   - Add a load animation (e.g., `Fade`) to the scrollable widget.
+   - Set the animation duration to approximately `1200 ms`.
+   - Add a `Delay Action` before the scroll action (e.g., `700 ms`).
+
+   ![](../assets/20250430121250214649.png)
+
+   :::tip
+   Combining a delay with animation prevents the scroll action from executing before the widget appears, creating a smoother transition.
+   :::
+
+:::info[Additional Resources]
+Refer to **[Scroll To Action Failing on Page Load](https://intercom.help/flutterflow/en/articles/7047006-scroll-to-action-is-not-working-when-used-on-page-load)** for more troubleshooting help.
+:::
\ No newline at end of file
diff --git a/docs/troubleshooting/migrate-widget-issues/store_custom_widget_output_using_app_state.md b/docs/troubleshooting/migrate-widget-issues/store_custom_widget_output_using_app_state.md
new file mode 100644
index 00000000..8ef0e1c3
--- /dev/null
+++ b/docs/troubleshooting/migrate-widget-issues/store_custom_widget_output_using_app_state.md
@@ -0,0 +1,32 @@
+---
+keywords: ['custom', 'widgets', 'app state', 'output']
+slug: /store-custom-widget-output-using-app-state
+title: Store Custom Widget Output Using App State
+---
+
+# Store Custom Widget Output Using App State
+
+To use the output from a custom widget elsewhere in your project, you can store its value in an app state variable. FlutterFlow does not directly support retrieving data from custom widgets, so this method provides an effective workaround.
+
+:::info[Prerequisites]
+- You have created a custom widget in your project.
+- You are familiar with the **[App State management](/concepts/state-management)** system in FlutterFlow.
+:::
+
+## Steps to Store Output from a Custom Widget
+
+1. **Create an App State Variable**  
+   Go to **App State**, then create a new app state variable that will hold the value returned by your custom widget.
+
+   ![](../assets/20250430121220879251.png)
+
+2. **Update the App State Variable from the Custom Widget**  
+   In your custom widget code, use `FFAppState()` to set the value of the app state variable.
+
+   ```js
+   FFAppState().update(() {
+     FFAppState().localvalue = 'setvalue';
+   });
+   ```
+
+   App state variables can be accessed anywhere in your FlutterFlow project, making them useful for sharing data between custom widgets and other parts of the app.
\ No newline at end of file