From 345a668cce053c3f52d71bdfc301ef187aa2da9f Mon Sep 17 00:00:00 2001
From: TheNoumanDev <76642732+TheNoumanDev@users.noreply.github.com>
Date: Sat, 7 Feb 2026 13:53:08 +0500
Subject: [PATCH] added the spans documentation for text
---
pages/widgets/text.mdx | 103 +++++++++++++++++++++++++++++------------
1 file changed, 73 insertions(+), 30 deletions(-)
diff --git a/pages/widgets/text.mdx b/pages/widgets/text.mdx
index b297f57..3157e93 100644
--- a/pages/widgets/text.mdx
+++ b/pages/widgets/text.mdx
@@ -1,23 +1,66 @@
-import { EnsemblePreview } from '../../components/ensemble-preview'
+import { EnsemblePreview } from "../../components/ensemble-preview";
# Text widget
Display and style text within your application.
-
+
## Properties
| Property | Type | Description |
| :------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------- |
| text | string | Your text content |
+| spans | array | List of text or widget spans for rich text rendering. When provided, enables mixed styling and inline widgets. [See spans](#spans) |
| visible | boolean | Toggle a widget visibility on/off. Note that an invisible widget will not occupy UI space, unless the visibilityTransitionDuration is specified. |
| styles | object | [See properties](#styles) |
+### Spans
+
+The `spans` property enables rich text with mixed styling and inline widgets within a single text flow. Each span can be either a text span or a widget span.
+
+#### Text Span Properties
+
+| Property | Type | Description |
+| :-------- | :----- | :------------------------------------------------------------------------ |
+| text | string | The text content for this span |
+| textStyle | object | Optional style override for this span. [See textStyle](#stylestextstyles) |
+| onTap | action | Optional action to execute when this span is tapped |
+
+#### Widget Span
+
+Any Ensemble widget (Icon, Image, etc.) can be embedded inline using the `widget` property.
+
+| Property | Type | Description |
+| :------- | :----- | :---------------------------------- |
+| widget | object | An Ensemble widget to render inline |
+
+#### Spans Example
+
+```yaml
+Text:
+ spans:
+ - text: "Read our "
+ - text: "Terms of Service"
+ textStyle:
+ color: 0xff4b93e7
+ decoration: underline
+ onTap:
+ navigateScreen:
+ name: HelpScreen
+ - text: " and "
+ - widget:
+ Icon:
+ name: info
+ size: 18
+ - text: " for more details."
+ styles:
+ textStyle:
+ fontSize: 16
+```
+
+This example renders: "Read our **Terms of Service** and [icon] for more details." where "Terms of Service" is styled as a tappable link and an info icon is embedded inline.
+
### Styles
| Property | Type | Description |
@@ -46,37 +89,37 @@ Display and style text within your application.
| backgroundGradient | object | Background gradient of the box [see properties ](#stylesbackgroundGradient) |
| expanded | boolean | If the parent is a Row or Column, this flag will stretch this widget in the appropriate direction. (e.g. stretch horizontally for parent of type Row) |
| visibilityTransitionDuration | number | Specify the duration in seconds when a widget animates between visible and not visible state. Note that setting this value will cause the widget to still occupy the UI space even when it is not visible. |
-| opacity | double | Adjusts the opacity of the widget. Values range from 0 (fully transparent) to 1 (opaque). Default is `1`. |
+| opacity | double | Adjusts the opacity of the widget. Values range from 0 (fully transparent) to 1 (opaque). Default is `1`. |
| elevation | integer | The z-coordinate at which to place this material relative to its parent. A non-zero value will show a shadow, with its size relative to the elevation value. Minimum value: 0, Maximum value: 24 |
| elevationShadowColor | integer or string | The shadow color for the elevation, which can be represented in different formats. It can be specified as a number, a predefined color name, or a hexadecimal value starting with '0x'. `transparent` `black` `blue` `white` `red` `grey` `teal` `amber` `pink` `purple` `yellow` `green` `brown` `cyan` `indigo` `lime` `orange` |
| elevationBorderRadius | string or integer | The border radius of the widget.This can be specified using CSS-like notation with 1 to 4 integers. Minimum value: 0. |
| alignment | string | The alignment of the widget relative to its parent. `topLeft`, `topCenter`, `topRight`, `centerLeft`, `center`, `centerRight`, `bottomLeft`, `bottomCenter`, `bottomRight` |
-| maxLines | integer | The maximum number of lines to display before truncating the text. Default is 3 when [expandable] is set to true. |
-| expandable | boolean | Default: false. When set to true, text will be truncated with the [expandLabel] as the text when it overflows the maxLines. |
-| expandLabel | string | Default: '...show more'. Default is in English. When expandable is set to true, expandLabel will be displayed as a clickable link at the end of the text to show the full text. If you want text for each language, use Ensemble's translation feature and specify a token here instead of hardcoding the text. |
-| collapseLabel | string | Default: ' show less'. Default is in English. When text is in the expanded state, collapseLabel will be displayed as a clickable link at the end of the text to show the truncated text. If you want text for each language, use Ensemble's translation feature and specify a token here instead of hardcoding the text. |
-| expandTextStyle | TextStyle | Default: textStyle of the Text widget with color changed to blue. The [TextStyle] of the expand/collapse label. Applicable only when [expandable] is set to true. |
+| maxLines | integer | The maximum number of lines to display before truncating the text. Default is 3 when [expandable] is set to true. |
+| expandable | boolean | Default: false. When set to true, text will be truncated with the [expandLabel] as the text when it overflows the maxLines. |
+| expandLabel | string | Default: '...show more'. Default is in English. When expandable is set to true, expandLabel will be displayed as a clickable link at the end of the text to show the full text. If you want text for each language, use Ensemble's translation feature and specify a token here instead of hardcoding the text. |
+| collapseLabel | string | Default: ' show less'. Default is in English. When text is in the expanded state, collapseLabel will be displayed as a clickable link at the end of the text to show the truncated text. If you want text for each language, use Ensemble's translation feature and specify a token here instead of hardcoding the text. |
+| expandTextStyle | TextStyle | Default: textStyle of the Text widget with color changed to blue. The [TextStyle] of the expand/collapse label. Applicable only when [expandable] is set to true. |
### styles.textStyles
-| Property | Type | Description |
-| :----------------- | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| fontFamily | string | Set the font family applicable for all widgets inside this container, see the list of all available font families [here](https://github.com/material-foundation/flutter-packages/blob/main/packages/google_fonts/generator/families_supported). |
-| fontSize | integer | Sets the size of the text. |
-| fontWeight | string | The thickness of the glyphs used to draw the text. `light` `normal` `bold` `w100` `w200` `w300` `w400` `w500` `w600` `w700` ` w800``w900 ` |
-| color | integer or string | The color specification for the text, icons, divider etc, which can be represented in different formats. It can be specified as a number, a predefined color name, or a hexadecimal value starting with '0x'. `transparent` `black` `blue` `white` `red` `grey` `teal` `amber` `pink` `purple` `yellow` `green` `brown` `cyan` `indigo` `lime` `orange` |
-| overflow | string | Set treatment of text longer than available space `wrap` `visible` `clip` `ellipsis` |
-| backgroundColor | integer or string | Background color of the box. which can be represented in different formats. It can be specified as a number, a predefined color name, or a hexadecimal value starting with '0x'. `transparent` `black` `blue` `white` `red` `grey` `teal` `amber` `pink` `purple` `yellow` `green` `brown` `cyan` `indigo` `lime` `orange` |
-| fontfamily | string | Allows users to chose a specific font-family other than the default one. |
-| decoration | string | A linear decoration to draw near the text or whether to slant the glyphs in font. `none` `lineThrough` `underline` `overline` |
-| decorationStyle | string | The style in which to paint the text decorations (e.g., dashed). `solid` `double` `dotted` `dashed` `wavy` |
-| decorationColor | [Color](#Color) | The color of the decoration. |
-| decorationThickness| number | The thickness of the decoration. |
-| isItalic | boolean | Whether the text should be italic or not |
-| lineHeightMultiple | integer | A multiple of the fontSize to determine the line height. (e.g. 2.0 means the line height is double the height the font size occupies). Default null. (note that 1.0 is not the default depending on the font) |
-| letterSpacing | integer | The amount of space (in logical pixels) to add between each letter. A negative value can be used to bring the letters closer. |
-| wordSpacing | integer | The amount of space (in logical pixels) to add at each sequence of white-space (i.e. between each word). A negative value can be used to bring the words closer. |
-| gradient | object | Using this property we can apply gradient to our text |
+| Property | Type | Description |
+| :------------------ | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| fontFamily | string | Set the font family applicable for all widgets inside this container, see the list of all available font families [here](https://github.com/material-foundation/flutter-packages/blob/main/packages/google_fonts/generator/families_supported). |
+| fontSize | integer | Sets the size of the text. |
+| fontWeight | string | The thickness of the glyphs used to draw the text. `light` `normal` `bold` `w100` `w200` `w300` `w400` `w500` `w600` `w700` `w800``w900` |
+| color | integer or string | The color specification for the text, icons, divider etc, which can be represented in different formats. It can be specified as a number, a predefined color name, or a hexadecimal value starting with '0x'. `transparent` `black` `blue` `white` `red` `grey` `teal` `amber` `pink` `purple` `yellow` `green` `brown` `cyan` `indigo` `lime` `orange` |
+| overflow | string | Set treatment of text longer than available space `wrap` `visible` `clip` `ellipsis` |
+| backgroundColor | integer or string | Background color of the box. which can be represented in different formats. It can be specified as a number, a predefined color name, or a hexadecimal value starting with '0x'. `transparent` `black` `blue` `white` `red` `grey` `teal` `amber` `pink` `purple` `yellow` `green` `brown` `cyan` `indigo` `lime` `orange` |
+| fontfamily | string | Allows users to chose a specific font-family other than the default one. |
+| decoration | string | A linear decoration to draw near the text or whether to slant the glyphs in font. `none` `lineThrough` `underline` `overline` |
+| decorationStyle | string | The style in which to paint the text decorations (e.g., dashed). `solid` `double` `dotted` `dashed` `wavy` |
+| decorationColor | [Color](#Color) | The color of the decoration. |
+| decorationThickness | number | The thickness of the decoration. |
+| isItalic | boolean | Whether the text should be italic or not |
+| lineHeightMultiple | integer | A multiple of the fontSize to determine the line height. (e.g. 2.0 means the line height is double the height the font size occupies). Default null. (note that 1.0 is not the default depending on the font) |
+| letterSpacing | integer | The amount of space (in logical pixels) to add between each letter. A negative value can be used to bring the letters closer. |
+| wordSpacing | integer | The amount of space (in logical pixels) to add at each sequence of white-space (i.e. between each word). A negative value can be used to bring the words closer. |
+| gradient | object | Using this property we can apply gradient to our text |
### styles.gradient