custom_text

Description:

custom text

A highly customisable text widget that enables decorations and gesture actions, and
a special TextEditingController that makes some of the features available also
in a text field.
This package is useful for making partial strings in text (e.g. URLs, email addresses
or phone numbers) react to tap, long-press and hover gestures, or for only highlighting
particular strings with colors and different font settings. You can configure the appearance
and the behaviour using multiple definitions consisting of regular expressions, text styles,
gesture handlers, etc.

Usage by example #
Most of the examples here are included in the sample app in the example folder.
Just click on the link below to see it in action on the web.
Web Demo
The app shows the source code with keywords highlighted, which itself is made possible
by this package (plus the highlight package used as an external parser).




⭐ Simplest example #
A very basic example of how to apply a colour to URLs and email addresses using preset
matchers.
Code / Demo


Click to see the details

Gestures are not available on the coloured strings in this example.
CustomText(
'URL: https://example.com/\n'
'Email: [email protected]',
definitions: const [
TextDefinition(matcher: UrlMatcher()),
TextDefinition(matcher: EmailMatcher()),
],
matchStyle: const TextStyle(color: Colors.lightBlue),
)
copied to clipboard
Preset matchers
The matchers listed below are for general use.
If a stricter pattern is necessary, overwrite the preset pattern or create a custom matcher.

UrlMatcher for URLs
UrlLikeMatcher for URL-like strings
EmailMatcher for email addresses
TelMatcher for phone numbers
LinkMatcher for Markdown-style links or for other strings to be handled
by SelectiveDefinition



⭐ Styles and actions per definition #
An example to decorate URLs, email addresses and phone numbers, and also enable them
to be tapped and long-pressed.
Code / Demo


Click to see the details

All the three are styled, but only phone numbers among them are styled differently with
the unique matchStyle and tapStyle.
Tip:
To open a browser or another app when a string is tapped or long-pressed, use the
url_launcher package or equivalent in the onTap and/or onLongPress handlers.
CustomText(
'URL: https://example.com/\n'
'Email: [email protected]\n'
'Tel: +1-012-3456-7890',
definitions: [
const TextDefinition(matcher: UrlMatcher()),
const TextDefinition(matcher: EmailMatcher()),
TextDefinition(
matcher: const TelMatcher(),
// Styles and handlers specified in a definition take
// precedence over the equivalent arguments of CustomText.
matchStyle: const TextStyle(
color: Colors.green,
decoration: TextDecoration.underline,
),
tapStyle: const TextStyle(color: Colors.orange),
onTap: (details) => print(details.actionText),
onLongPress: (details) => print('[Long press] ${details.actionText}'),
),
],
matchStyle: const TextStyle(
color: Colors.lightBlue,
decoration: TextDecoration.underline,
),
tapStyle: const TextStyle(color: Colors.indigo),
onTap: (details) => print(details.actionText),
onLongPress: (details) => print('[Long press] ${details.actionText}'),
)
copied to clipboard


⭐ Overwriting a match pattern #
An example to replace the default pattern of TelMatcher.
Code / Demo


Click to see the details

The new pattern here regards only the {3 digits}-{4 digits}-{4 digits} format
as a phone number.
CustomText(
'Tel: +1-012-3456-7890',
definitions: const [
TextDefinition(matcher: TelMatcher(r'\d{3}-\d{4}-\d{4}')),
],
matchStyle: const TextStyle(color: Colors.lightBlue),
onTap: (details) => print(details.actionText),
)
copied to clipboard


⭐ Custom match pattern #
An example to parse hashtags with a custom pattern and apply styles to them.
Code / Demo


Click to see the details

A hashtag has a wide variety of definitions, but here as an example, it is defined
as a string that starts with "#" followed by an alphabet and then alphanumerics,
and is enclosed with white spaces.
TextDefinition(
matcher: PatternMatcher(r'(?<=\s|^)\#[a-zA-Z][a-zA-Z0-9]{1,}(?=\s|$)'),
),
copied to clipboard
Alternatively, you can define a matcher by extending TextMatcher.
This allows you to distinguish the custom matcher from others by its unique type.
class HashTagMatcher extends TextMatcher {
const HashTagMatcher()
: super(r'(?<=\s|^)\#[a-zA-Z][a-zA-Z0-9]{1,}(?=\s|$)');
}
copied to clipboard
CustomText(
'Hello world! #CustomText',
definitions: const [
TextDefinition(matcher: HashTagMatcher()),
],
matchStyle: const TextStyle(color: Colors.lightBlue),
onTap: (details) {
if (details.element.matcherType == HashTagMatcher) {
...;
}
},
)
copied to clipboard


⭐ SelectiveDefinition #
An example to parse a markdown-style link in the format of [shown text](url)
and make it tappable.
Code / Demo


Click to see the details

SelectiveDefinition allows to select the string to display and the string to
be passed to gesture callbacks individually.
The shownText and actionText functions receive a [TextElement] object
containing various pieces of information provided by the parser. For its
details, see the document of the text_parser package used internally in
this package.
CustomText(
'Tap [here](Tapped!)',
definitions: [
SelectiveDefinition(
matcher: const LinkMatcher(),
// `shownText` is used to choose the string to display.
shownText: (element) => element.groups[0]!,
// `actionText` is used to choose the string to be passed
// to the `onTap`, `onLongPress` and `onGesture` handlers.
actionText: (element) => element.groups[1]!,
),
],
matchStyle: TextStyle(color: Colors.blue),
hoverStyle: TextStyle(color: Colors.blue, decoration: TextDecoration.underline),
onTap: (details) => print(details.actionText),
)
copied to clipboard
LinkMatcher is handy if used together with SelectiveDefinition, not only for
making a text link but also for just decorating the bracketed strings (without
showing the bracket symbols), in which case [strings]() is used as a marker to
indicate which strings to be decorated.
// "def" and "jkl" are displayed in red.
CustomText(
'abc[def]()ghi[jkl]()',
definitions: [
SelectiveDefinition(
matcher: const LinkMatcher(),
shownText: (element) => element.groups[0]!,
),
],
matchStyle: const TextStyle(color: Colors.red),
)
copied to clipboard


⭐ SpanDefinition #
An example to display both text and widgets.
Code / Demo


Click to see the details

SpanDefinition enables a certain portion of text to be replaced with an arbitrary
InlineSpan. The builder function receives a [TextElement] object containing
various pieces of information provided by the parser so that you can use it
to flexibly build an InlineSpan.
Text styles, gesture handlers and the mouse cursor type are applied to the entire
InlineSpan returned by the builder function. In this example, hovering is detected
on all the children specified in the second SpanDefinition, i.e. the text in a TextSpan
is decorated based on hoverStyle while the mouse pointer is hovering over the logo
as well as over the text.
CustomText(
'Hover and click >> [logo]Flutter',
definitions: [
SpanDefinition(
matcher: const PatternMatcher('>>'),
builder: (element) => const WidgetSpan(
child: Icon(Icons.keyboard_double_arrow_right, ...),
),
),
SpanDefinition(
matcher: const PatternMatcher(r'\[logo\](\w+)'),
builder: (element) => TextSpan(
children: [
const WidgetSpan(child: FlutterLogo()),
const WidgetSpan(child: SizedBox(width: 2.0)),
TextSpan(text: element.groups.first),
],
),
matchStyle: TextStyle(color: Colors.blue),
hoverStyle: TextStyle(color: Colors.blue, decoration: TextDecoration.underline),
onTap: (details) => print(details.element.groups.first!),
),
],
)
copied to clipboard


⭐ Real hyperlinks #
An example to embed real hyperlinks for the web by making use of SpanDefinition
together with the Link widget of url_launcher.
Code / Demo


Click to see the details

Notes:
As you can see in the screencast above, WidgetSpans are vertically misaligned
with plain text on the web. It is due to issues existing on the Flutter SDK side.
CustomText(
'Please visit [pub.dev](https://pub.dev/packages/custom_text) and ...',
definitions: [
SpanDefinition(
matcher: const LinkMatcher(),
builder: (element) {
return WidgetSpan(
alignment: PlaceholderAlignment.middle,
child: Link(
uri: Uri.parse(element.groups[1]!),
target: LinkTarget.blank,
builder: (context, openLink) {
return GestureDetector(
onTap: openLink,
child: Text(element.groups[0]!),
);
},
),
);
},
matchStyle: const TextStyle(color: Colors.blue),
hoverStyle: const TextStyle(color: Colors.blue, decoration: TextDecoration.underline),
mouseCursor: SystemMouseCursors.click,
),
],
)
copied to clipboard


⭐ Changing mouse cursor and text style on hover #
An example to change the mouse cursor type on certain substrings.
Code / Demo


Click to see the details

This is easily possible by just passing your desired type to mouseCursor.
If a tap handler (onTap or onLongPress) is specified and mouseCursor is not,
SystemMouseCursors.click is automatically used for the tappable region.
A different text style can also be applied on hover using hoverStyle either in CustomText
or in a definition.
Tip:
Use hoverStyle and omit tapStyle if you want the same style for tap and hover.
CustomText(
'URL: https://example.com/\n'
'Email: [email protected]',
definitions: [
const TextDefinition(
matcher: UrlMatcher(),
matchStyle: TextStyle(
color: Colors.grey,
decoration: TextDecoration.lineThrough,
),
// `SystemMouseCursors.forbidden` is used for URLs.
mouseCursor: SystemMouseCursors.forbidden,
),
TextDefinition(
matcher: const EmailMatcher(),
matchStyle: const TextStyle(
color: Colors.lightBlue,
decoration: TextDecoration.underline,
),
tapStyle: const TextStyle(color: Colors.green),
// Text is shadowed while the mouse pointer hovers over it.
hoverStyle: TextStyle(
color: Colors.lightBlue,
shadows: ...,
),
// `SystemMouseCursors.click` is automatically used for
// tappable elements even if `mouseCursor` is not specified.
onTap: (details) => print(details.actionText),
),
],
)
copied to clipboard


⭐ Event positions and onGesture #
An example to trigger an action by a secondary or tertiary button press or a
mouse enter or exit gesture.
Code / Demo


Click to see the details

The onGesture handler is called on an event of a non-primary button or mouse
gesture.
You can check the event type with gestureKind contained in the GestureDetails
object which is passed to the handler function. The object also has the global
and local positions where an event happened.
Notes:

onGesture does not handle events of the primary button. Use onTap and/or
onLongPress instead.
Unlike onTap and onLongPress, whether onGesture is specified does not
affect text styling.
The handler function is called one microsecond or more after the actual
occurrence of an event.

This is due to a workaround for preventing the function from being called
more times than expected by updates of the text span.





⭐ CustomText.spans #
An example of the CustomText.spans constructor that allows to use a list of InlineSpans
instead of plain text.
Code / Demo


Click to see the details

This constructor is useful if you already have styled spans and want to decorate them
additionally.
In this example, the match pattern matches the range containing multiple InlineSpans
including a WidgetSpan, and the specified styles and gestures are applied to that range.
CustomText.spans(
style: const TextStyle(fontSize: 40.0),
definitions: [
TextDefinition(
// WidgetSpan is matched by `\uFFFC` or `.` in a match pattern.
matcher: const PatternMatcher('Flutter devs\uFFFC'),
matchStyle: const TextStyle(color: Colors.blue),
hoverStyle: TextStyle(color: Colors.blue.shade300),
mouseCursor: SystemMouseCursors.forbidden,
onGesture: (details) => output(details.gestureKind.name),
),
],
spans: [
const TextSpan(text: 'Hi, '),
const TextSpan(
text: 'Flutter',
style: TextStyle(
fontWeight: FontWeight.bold,
shadows: [Shadow(blurRadius: 4.0, color: Colors.cyan)],
),
),
const TextSpan(text: ' devs'),
WidgetSpan(
alignment: PlaceholderAlignment.middle,
child: Builder(
builder: (context) {
// Text style is available also in WidgetSpan via DefaultTextStyle.
final style = DefaultTextStyle.of(context).style;
return Icon(
Icons.flutter_dash,
size: style.fontSize,
color: style.color,
);
},
),
),
],
)
copied to clipboard
Notes:

Arguments other than text and style in the spans passed to spans are
not used even if specified.



⭐ CustomText with preBuilder #
An example of preBuilder that allows to apply decorations and then additionally
apply more decorations and enable gestures.
Code / Demo


Click to see the details

It has similar use cases to CustomText.spans, but is more helpful when it is
not easy to compose complex spans manually.
The example below makes "KISS" and "Keep It Simple, Stupid!" bold, and then
applies a colour to capital letters contained in them.
CustomText(
'KISS is an acronym for "Keep It Simple, Stupid!".',
definitions: const [
TextDefinition(
// This pattern is used for parsing the TextSpan built
// by preBuilder, not for the original text.
matcher: PatternMatcher('[A-Z]'),
matchStyle: TextStyle(color: Colors.red),
),
],
preBuilder: CustomSpanBuilder(
definitions: [
const TextDefinition(
// This pattern is used for parsing the original text.
matcher: PatternMatcher('KISS|Keep.+Stupid!'),
matchStyle: TextStyle(fontWeight: FontWeight.bold),
),
],
),
)
copied to clipboard
Notes:

Parsing is performed first in the builder and then in CustomText itself. It
is important to understand that the match patterns in the builder are used for
the original text and the patterns in CustomText are used for the TextSpan
built by the builder.
Parsing and building of spans are avoided if not necessary, but still happen
in two steps as written above when unavoidable. Be careful how much it affects
the performance of your app.
Gesture callbacks and mouseCursor in the builder are not used even if specified.



⭐ CustomTextEditingController #
An example of CustomTextEditingController that makes some of the CustomText
functionality available in an editable text.
Code / Demo


Click to see the details

final controller = CustomTextEditingController(
text: 'abcde [email protected]\nhttps://example.com/ #hashtag',
definitions: [
const TextDefinition(
matcher: HashTagMatcher(),
matchStyle: TextStyle(color: Colors.orange),
hoverStyle: TextStyle(color: Colors.red),
),
...
],
);
copied to clipboard
@override
Widget build(BuildContext context) {
return TextField(
controller: controller,
...,
);
}
copied to clipboard
Notes:

CustomTextEditingController does not support SelectiveDefinition and SpanDefinition.
An error is raised on iOS simulators (not on real devices) if the initial text and
onTap, onLongPress or onGesture are specified.

See https://github.com/flutter/flutter/issues/97433.


Debouncing of text parsing is available as an experimental feature for getting slightly
better performance in handling long text.

Pass some duration to debounceDuration to enable the feature.
Use it at your own risk.
Text input will be still slow even with debouncing because
Flutter itself has performance issues
in editable text.





⭐ Using an external parser #
An example of using an external parser instead of the internal one.
Code / Demo


Click to see the details

ParserOptions.external helps you when a different parser you already have does
a better job or can do what is difficult with the default parser.
// These empty matchers are used to distinguish the matcher types of
// text elements parsed by an external parser.
// Each of the elements created by the parser needs to have the type
// of one of these matchers or `TextMatcher`.
class KeywordMatcher extends TextMatcher {
const KeywordMatcher() : super('');
}

class StringMatcher extends TextMatcher {
const StringMatcher() : super('');
}
copied to clipboard
CustomText(
sourceCode,
parserOptions: ParserOptions.external(
(text) => parseLanguage(text, language: 'dart'),
),
definitions: [
const TextDefinition(
matcher: KeywordMatcher(),
matchStyle: TextStyle(color: Colors.orange),
),
const TextDefinition(
matcher: StringMatcher(),
matchStyle: TextStyle(color: Colors.teal),
),
...
],
);
copied to clipboard
Notes:

The external parser must generate a list of TextElements.
If an existing external parser creates hierarchical nodes, they need to be
flattened as this package only supports a flat list.
If a custom parser is used with CustomTextEditingController, the TextElements
generated by the parser must all together constitute the original text.
Otherwise, it will cause unexpected behaviours.

This does not apply to CustomText.





Limitations #

decorationColor does not automatically inherit the text colour in Material 3.
See https://github.com/flutter/flutter/issues/129553.
The regular expression pattern of TelMatcher contains a lookbehind assertion.
It is not supported in Safari versions before 16.4.
CustomTextEditingController raises an error on iOS simulators (not on real devices)
if the initial text and onTap, onLongPress or onGesture are specified.
See https://github.com/flutter/flutter/issues/97433.

Links #

text_parser

CustomText is dependent on the text_parser package made by the same author.
See its documents for details if you're interested or seek troubleshooting on parsing.