pub package GitHub stars GitHub forks GitHub license GitHub issues

Language: English | 中文


Hypertext is a highly extensible rich text widget that automatically parses styles.

Preview

View online demo

EN ZH

Features

  1. Built-in support for common HTML-like tags, such as:

    • Links (with tap and long-press events)
    • Images
    • Text styles: italic, bold, strikethrough, underline, text color, gradients, etc.
    • ...

  2. Event handling support

  3. Custom markup support

  4. Customizable color name mapping to easily support multi-theme scenarios

  5. Text style inheritance for WidgetSpan's inner child

Table of contents

Getting Started

dependencies:
  flutter_hypertext: ^0.0.1+8

import 'package:flutter_hypertext/markup.dart';

Hypertext("Hello <color=red>Hypertext</color>")

Supported Parameters

Parameter Default Description
onMarkupEvent Receive events like a
lowercaseAttrName true Convert attribute names to lowercase
lowercaseElementName true Convert element names to lowercase
ignoreErrorMarkup false Ignore erroneous tags
colorMapper kBasicCSSColors Color name mapping (default is CSS basic colors)
markups kDefaultMarkups Supported markup tags

Global default configuration can be set via HypertextThemeExtension

Custom Markups

Defining a Custom Markup:

class CustomMarkup extends TagMarkup {
  const CustomMarkup() : super('your-tag');

  @override
  HypertextSpan onMarkup(List<HypertextSpan>? children, MarkupContext ctx) {
    return HypertextTextSpan(children: children, style: TextStyle());
    return HypertextWidgetSpan(child: child);
  }
}

Setting Custom Markup:

Hypertext(
    text,
    markups: [...kDefaultMarkups, CustomMarkup()],
)

Or

ThemeData(
  extensions: [HypertextThemeExtension(markups: [...kDefaultMarkups, CustomMarkup()])],
)

Use Cases

  1. Rich text in multiple languages
  2. Rich text with multiple themes
  3. Highlighting keywords (search, mentions, topics...)

Predefined Markup Tags

1) LinkMarkup

Marks a range as a hyperlink, specifically for adding click events.

Tag Name: a

Parameters:

Parameter Value Required Description
href URI string ✅ URI
tap - ☑️ Handle click (can also specify long-press)
long-press - ☑️ Handle long press (can also specify tap)
title String ☑️ Tooltip content
cursor basic click text defer... ☑️ See SystemMouseCursors
alignment baseline middle top bottom... ☑️ See PlaceholderAlignment
baseline alphabetic ideographic ☑️ See TextBaseline

Example:

<a href="https://example.com">go</a>
<a href="app://op" custom-attr=foo title="User Foo" long-press tap>foo</a> <!-- Supports both tap and long-press -->

Hypertext(
    text,
    onMarkupEvent: (MarkupEvent event){
      // event.tag
      // event.data
    },
);

2) StyleMarkup

Sets text styles for a specified range, such as text color, background color, font size, font family, font weight, italic, text decorations (underline, overline, strikethrough)...

Tag: style

Parameters:

Parameter Value Required Description
color Hex Color or Color Name ☑️ Text color, default supports CSS Basic ColorskBasicCSSColors
background Hex Color or Color Name ☑️ Text background color
size double ☑️ Text size
font-family font family name ☑️ Font family
weight 100~900、bold、normal ☑️ See FontWeight
font-style normal italic ☑️ Font style FontStyle
decor none underline overline lineThrough ☑️ Text decoration TextDecoration
decor-style double dashed dotted solid wavy ☑️ Decoration style TextDecorationStyle
decor-color Hex Color or Color Name ☑️ Decoration color
thickness double ☑️ Decoration line thickness

Example:

<style color=red background=white size=20 weight=900>hypertext</style>
<style decor=underline decor-color=#F00 thickness=2>hypertext</style>

StyleMarkup is a superset of the following tags:

1. FontWeightMarkup

Tag: weight

Parameter Value Required Description
weight (simplify) 100~900、bold、normal ✅️ See FontWeight

Example:

<weight=500>foo</weight>
<weight weight=100>bar</weight>

2. BoldMarkup

Tags: b bold strong

Parameter Value Required Description
weight (simplify) 100~900、bold、normal ✅️ See FontWeight 
<b>Hypertext</b>
<bold=900>Hypertext</bold>
<strong weight=100>Hypertext</strong>

3. FontStyleMarkup

Tag: font-style

Parameter Value Required Description
font-style (simplify) normal italic ✅ See FontWeight

Example:

<font-style=italic>foo</font-style>
<font-style font-style=normal>bar</font-style>

4. ItalicMarkup

Tag: i

Example:

<i>bar</i>

5. TextDecorationMarkup

Tag: text-decor

Parameter Value Required Description
decor (simplify) none underline overline lineThrough ✅ Text decoration TextDecoration
style double dashed dotted solid wavy ☑️ Decoration style TextDecorationStyle
color Hex Color or Color Name ☑️ Decoration color
thickness double ☑️ Decoration line thickness

Example:

<text-decor=underline style=dotted>foo</text-decor>
<text-decor decor=lineThrough color=red thickness=2>bar</text-decor>

6. DelMarkup

Tag: del

Parameter Value Required Description
style double dashed dotted solid wavy ☑️ Decoration style TextDecorationStyle
color Hex Color or Color Name ☑️ Decoration color
thickness double ☑️ Decoration line thickness

Example:

<del color=red>bar</del>

7. UnderlineMarkup

Tag: u ins

Parameter Value Required Description
style double dashed dotted solid wavy ☑️ Decoration style TextDecorationStyle
color Hex Color or Color Name ☑️ Decoration color
thickness double ☑️ Decoration line thickness

Example:

<u style=wavy>bar</u>

8. ColorMarkup

Tag: color

Parameters:

Parameter Value Required Description
color (simplify) Hex Color or Color Name ✅ Text color

Example:

<color=red>bar</color>
<color color=#FF0>bar</color>

9. SizeMarkup

Tag: size

Parameters:

Parameter Value Required Description
size (simplify) double ✅ Text size

Example:

<size=red>bar</size>
<size color=#FF0>bar</size>

4) GradientMarkup

Sets a linear gradient for the specified range of text.

Tag: gradient

Parameters:

Parameter Value Required Description
colors Hex Color or Color Name ✅ Gradient colors
stops List ☑️ Values between 0.0 and 1.0 for gradient stops LinearGradient
rotation Angle (0~360) ☑️ Rotation angle for gradient
tile-mode clamp (default) repeated mirror decal ☑️ Tiling mode
alignment baseline middle top bottom... ☑️ See PlaceholderAlignment
baseline alphabetic ideographic ☑️ See TextBaseline

Example:

<gradient colors="red, green" rotation=45>bar</gradient>
<gradient colors="#F00,#00F" rotation=45>bar</gradient>

5) ImageMarkup

Add image, support custom parsing src and creating image widgets through imageBuilder.

Note The default implementation of network image is NetworkImage, which does not support disk caching. If necessary, please use ImageMarkup.imagebuilder.

Tag: img image

Parameters:

Parameter Value Required Description
src URI string ✅ Image path (supports http[s]://, asset://, path)
size List<double> ☑️ Image width and height (1~2 values)
width double ☑️ Image width
height double ☑️ Image height
fit fill contain cover fitWidth fitHeight none scaleDown ☑️ BoxFit modes
align topLeft center bottomLeft... ☑️ Alignment options
alignment baseline middle top bottom... ☑️ See PlaceholderAlignment
baseline alphabetic ideographic ☑️ See TextBaseline

Example:

<img src="https://example.com/avatar.png" size=50 fit=cover/>
<img src="asset://images/icon.png" size="50,100"/>
<img src="path/to/icon.png" width="50" height="50"/> <!--File path-->

6) GapMarkup

Adds space gaps.

Tag: gap

Parameters:

Parameter Value Required Description
gap (simplify) double ✅ Gap size

Example:

<gap=10 />
<gap gap="50"/>

7) PaddingMarkup

Adds padding inside an element.

Tag: padding

Parameters:

Parameter Value Required Description
padding (simplify) double ✅ Padding value (1~4 values)
hor List<double> ☑️ Horizontal padding (1~2 values)
ver List<double> ☑️ Vertical padding (1~2 values)
alignment baseline middle top bottom... ☑️ See PlaceholderAlignment
baseline alphabetic ideographic ☑️ See TextBaseline

Example:

<padding="10, 20">foo</padding> <!-- Set top/bottom padding to 10, left/right padding to 20 -->
<padding padding="50"/> <!-- Set all padding to 50 -->
<padding hor="10, 20"/> <!-- Set left padding to 10, right padding to 20 -->
<padding ver="20"/> <!-- Set vertical padding to 20 -->

Special Notes

Color Names

By default, CSS Basic ColorskBasicCSSColors are supported. You can customize color name mappings via Hypertext.colorMapper and HypertextThemeExtension.colorMapper.

Hex Colors

Supports the following formats:

  1. RGB, e.g., #0F0
  2. RGBA, e.g., #0F0F
  3. RRGGBB, e.g., #00FF00
  4. RRGGBBAA, e.g., #00FF00FF

Margin Values

Supports the following formats:

  1. 10 → left=10 top=10 right=10 bottom=10
  2. 10, 20 → left=20 top=10 right=20 bottom=10
  3. 10, 20, 30 → left=20 top=10 right=20 bottom=30
  4. 10, 20, 30, 40 → left=10 top=20 right=30 bottom=40

Things to Keep in Mind

  1. When customizing Markups, it is recommended to use HypertextTextSpan or HypertextWidgetSpan to help inherit styles from parent WidgetSpan for text within it.

TODO

  • ☑️ Improve selectability: Add built-in selectability options and pass selectability to WidgetSpan.

Libraries

hypertext
markup