# flutter_svg 0.13.0+1

An SVG rendering and widget library for Flutter, which allows painting and displaying Scalable Vector Graphics 1.1 files.




## Installing
```
export PUB_HOSTED_URL=https://pub.mirror.p-hatan.com
flutter pub add 'flutter_svg:0.13.0+1'
```
Published: 2019-05-07T02:52:03.648431Z
Expected archive SHA-256: 75382f2ce9b987a7b06b96edbdb0f5c7f8b8891cc4dbe41b2ce932fe4d80fc06

Available in cache; verification: upstream_checksum
## Direct dependencies
- flutter: map[sdk:flutter]
- meta: ^1.1.2
- path_drawing: ^0.4.1
- vector_math: ^2.0.4
- xml: ^3.3.1

## Package README (untrusted upstream documentation)
# flutter_svg

[![Pub](https://img.shields.io/pub/v/flutter_svg.svg)](https://pub.dartlang.org/packages/flutter_svg) [![Build Status](https://travis-ci.org/dnfield/flutter_svg.svg?branch=master)](https://travis-ci.org/dnfield/flutter_svg) [![Coverage Status](https://coveralls.io/repos/github/dnfield/flutter_svg/badge.svg?branch=master)](https://coveralls.io/github/dnfield/flutter_svg?branch=master)

<!-- markdownlint-disable MD033 -->
<img src="/../master/example/assets/flutter_logo.svg?sanitize=true" width="200px" alt="Flutter Logo which can be rendered by this package!">
<!-- markdownlint-enable MD033 -->

Draw SVG (and _some_ Android VectorDrawable (XML)) files on a Flutter Widget.

## Getting Started

This is a Dart-native rendering library. Issues/PRs will be raised in Flutter
and flutter/engine as necessary for features that are not good candidates for
Dart implementations (especially if they're impossible to implement without
engine support). However, not everything that Skia can easily do needs to be
done by Skia; for example, the Path parsing logic here isn't much slower than
doing it in native, and Skia isn't always doing low level GPU accelerated work
where you might think it is (e.g. Dash Paths).

All of the SVGs in the `assets/` folder (except the text related one(s)) now
have corresponding PNGs in the `golden/` folder that were rendered using
`flutter test tool/gen_golden.dart` and compared against their rendering output
in Chrome. Automated tests will continue to compare these to ensure code changes
do not break known-good renderings.

Basic usage (to create an SVG rendering widget from an asset):

```dart
final String assetName = 'assets/image.svg';
final Widget svg = new SvgPicture.asset(
  assetName,
  semanticsLabel: 'Acme Logo'
);
```

You can color/tint the image like so:

```dart
final String assetName = 'assets/up_arrow.svg';
final Widget svgIcon = new SvgPicture.asset(
  assetName,
  color: Colors.red,
  semanticsLabel: 'A red up arrow'
);
```

The default placeholder is an empty box (`LimitedBox`) - although if a `height`
or `width` is specified on the `SvgPicture`, a `SizedBox` will be used instead
(which ensures better layout experience). There is currently no way to show an
Error visually, however errors will get properly logged to the console in debug
mode.

You can also specify a placeholder widget. The placeholder will display during
parsing/loading (normally only relevant for network access).

```dart
// Will print error messages to the console.
final String assetName = 'assets/image_that_does_not_exist.svg';
final Widget svg = new SvgPicture.asset(
  assetName,
);

final Widget networkSvg = new SvgPicture.network(
  'https://site-that-takes-a-while.com/image.svg',
  semanticsLabel: 'A shark?!',
  placeholderBuilder: (BuildContext context) => new Container(
      padding: const EdgeInsets.all(30.0),
      child: const CircularProgressIndicator()),
);
```

If you'd like to render the SVG to some other canvas, you can do something like:

```dart
import 'package:flutter_svg/flutter_svg.dart';
final String rawSvg = '''<svg viewBox="...">...</svg>''';
final DrawableRoot svgRoot = await svg.fromSvgString(rawSvg, rawSvg);

// If you only want the final Picture output, just use
final Picture picture = svgRoot.toPicture();

// Otherwise, if you want to draw it to a canvas:
// Optional, but probably normally desirable: scale the canvas dimensions to
// the SVG's viewbox
svgRoot.scaleCanvasToViewBox(canvas);

// Optional, but probably normally desireable: ensure the SVG isn't rendered
// outside of the viewbox bounds
svgRoot.clipCanvasToViewBox(canvas);
svgRoot.draw(canvas, size);
```

The `SvgPicture` helps to automate this logic, and it provides some convenience
wrappers for getting assets from multiple sources and caching the resultant
`Picture`. _It does not render the data to an `Image` at any point_; you
certainly can do that in Flutter, but you then lose some of the benefit of
having a vector format to begin with.

While I'm making every effort to avoid needlessly changing the API, it's not
guarnateed to be stable yet (hence the pre-1.0.0 version). To date, the biggest
change is deprecating the `SvgImage` widgets in favor of `SvgPicture` - it
became very confusing to maintain that name, as `Picture`s are the underlying
mechanism for rendering rather than `Image`s.

See [main.dart](/../master/example/lib/main.dart) for a complete sample.

## Use Cases

- Your designer creates a vector asset that you want to include without
  converting to 5 different raster format resolutions.
- Your vector drawing is meant to be static and non (or maybe minimally)
  interactive.
- You want to load SVGs dynamically from network sources at runtime.
- You want to paint SVG data and render it to an image.

## TODO

This list is not very well ordered. I'm mainly picking up things that seem
interesting or useful, or where I've gotten a request to fix something/example
of something that's broken.

- Text support (partially implemented).
- Support Radial gradients that use percentages in the offsets.
- Dash path with percentage dasharray values (need good examples).
- Display/visibility support. My hunch is that this is usually used more for SVG
  specific interactivity, which isn't supported or planned.
- Inheritance of inheritable properties (~~necessary? preprocess?~~ significant
  progress, still some rough edges, particularly for definitions).
- Support for minimal CSS/styles? See also [usvg](https://github.com/RazrFalcon/resvg/tree/master/usvg)
  (partial style attribute mostly supported).
- Markers.
- Filters/effects (will require upstream engine changes, but doable).
- Android Vector Drawable support beyond PoC - I'm willing to put more time into
  this if there's actually demand, but it doesn't come up often.

## Probably out of scope/non-goals

- SMIL animations. That just seems crazy. I think it'll be possible to animate
  the SVG but probably in a more Flutter driven way.
- Interactivity/events in SVG.
- Full (any?) CSS support - preprocess your SVGs (perhaps with [usvg](https://github.com/RazrFalcon/resvg/tree/master/usvg) or [scour](https://github.com/scour-project/scour) to get rid of all CSS?).
- Scripting in SVGs
- Foreign elements
- Rendering properties/hints

## SVG sample attribution

SVGs in `/assets/w3samples` pulled from [W3 sample files](https://dev.w3.org/SVG/tools/svgweb/samples/svg-files/)

SVGs in `/assets/deborah_ufw` provided by @deborah-ufw

SVGs in `/assets/simple` are pulled from trivial examples or generated to test
basic functionality - some of them come directly from the SVG 1.1 spec. Some
have also come or been adapted from issues raised in this repository.

SVGs in `/assets/wikimedia` are pulled from [Wikimedia Commons](https://commons.wikimedia.org/wiki/Main_Page)

Android Drawables in `/assets/android_vd` are pulled from Android Documentation
and examples.

The Flutter Logo created based on the Flutter Logo Widget © Google.

The Dart logo is from
[dartlang.org](https://github.com/dart-lang/site-shared/blob/master/src/_assets/images/dart/logo%2Btext/horizontal/original.svg)
© Google

SVGs in `/assets/noto-emoji` are from [Google i18n noto-emoji](https://github.com/googlei18n/noto-emoji),
licensed under the Apache license.

Please submit SVGs this can't render properly (e.g. that don't render here the
way they do in chrome), as long as they're not using anything "probably out of
scope" (above).

## Changelog
# CHANGES

## 0.13.0+1

- Bump path_drawing dependency, which includes bug fixes in parsing.

## 0.13.0

- Updated SDK constraint to support new error message formats
- Updated error message formats
- Misc. updates for new SDK features

## 0.12.4

- Fixed `opacity` handling, particularly for groups. Previously, opacities were
  averaged together, which resulted in incorrect compositing (particularly if
  overlapping shapes were drawn within a group). Now, a new layer is created
  with the opacity applied to the whole. This may cause some performance
  degredation, but is more correct.
- Allow font-size to be specified in `px` (with an explicit postfix).
- Add `excludeFromSemantics` property for purely decorative SVGs. The default
  value is false.

## 0.12.3

- Fixed bug with stream completer unregistration.
- Fixed bug with text transforms in new parsing.
- Fixed bug with RGBA parsing for opacity

## 0.12.2

- Fixed bug with AVD parsing from strings.

## 0.12.1

- Support for `display="none"` and `visibility="hidden"`.

## 0.12.0

- **BREAKING** Avoid scaling based on devicePixelRatio. This turned out to be a
  mistake, and caused rendering inconsistencies across devices. It was
  particularly harmful on devices where the ratio was less than 1.0.
- Add `precachePicture` method to allow for pre-caching of SVG assets. Similar
  in functionality to `precacheImage` in the Flutter framework. Also added
  improvements to error handling in the various related routines.

## 0.11.0+1

- Format source code
- Remove unintentionally committed pubspec.lock

## 0.11.0

- Rewrote parsing logic to unpin dart-xml dependency, and bumped Dart XML
  dependency.
- Fix bug where unsupported elements could impact drawing. Unhandled elements
  that have children will now be completely ignored. This is technically a
  breaking change, as previously a child of an unsupported element could have
  been drawn if it was supported. Fixes [#126](https://github.com/dnfield/flutter_svg/issues/126).

## 0.10.4

- Fix bug in transform logic [#122](https://github.com/dnfield/flutter_svg/issues/122)
- Avoid defaulting to the rootBundle, using th DefaultAssetBundle instead when
  resolving pictures [#118](https://github.com/dnfield/flutter_svg/pull/118)

## 0.10.3

- Pin dart-xml to 3.2.5, as 3.3.0 is a breaking change (next release will
  address this).
- Support `px` postfixes on many double literals.

## 0.10.2

- Added a `semanticsLabel` property to `SvgPicture`.
- Updated tests to support async changes in Flutter's `Picture.toImage` method.
  - This is breaking for tests - tests will now require a more recent version of
    Flutter to run. It should not break consumers though.

## 0.10.1

This is technically a breaking release, but it also includes important fixes for
v0.10.0. Rather than splitting the breaking parts out in to v0.11.0 so soon
after the release of v0.10.0, I'm including some more breaking changes here.
This will not normally be done.

- Fix bug that caused `<stop>` elements that weren't self-closing to parse
  improperly.
- Many documentation updates/improvements.
- Added support for gradients that use `xlink:href`
- **BREAKING**: Changed some of the methods on `DrawableDefinitionServer` to
  support gradients better.
- **BREAKING**: Removed the `PaintServer` typedef, since this was only serving
  gradients and we need to have more control there for `xlink:href` support.

## 0.10.0+1

- Fix bug that caused an empty `<defs/>` element prevent rendering.

## 0.10.0

- Rewrite parsing to be more space efficient.
- Refactor parsing to enable more output possibilities.
- Create a dedicated SVG parsing class (SvgParser).
- Updates to text - better support for nested text/tspans.
- Miscellaneous bug fixes.
- Testing improvements.

## 0.9.0+1

- Fix inheritance issues with `text-anchor`.
- Fix a few inconsistencies in text anchor processing/positioning.

## 0.9.0

- **BREAKING** Improvements to text positioning. Thanks to @krispypen!

## 0.8.3

- Implement support for `clipPath` outside of `defs` eleemnts.
- Implement support for `use` in a `clipPath`.
- Recommend `usvg` rather than `svgcleaner` per author's recommendation.

## 0.8.2

- Make `DrawableNoop` implement `DrawableStyleable` to avoid crashing with
  certain unhandled elements.
- Improve error reporting for certain `<style>` element scenarios.

## 0.8.1

- Revert changes made on 0.7.0 to attempt to utilize `width` and `height`. These
  changes did not quite fix what they were intended to fix and caused problems
  they weren't intended to case.

## 0.8.0

- Made parsing `async` to support image loading.
- Added support for `<image>` elements.

## 0.7.0+1

- By default, `SvgPicture.asset` will now cache the asset. We already cached the
  final picture, but the caching included any color filtering provided on the
  image. This is problematic if the color is animated. See
  [dnfield/flutter_svg#33](https://github.com/dnfield/flutter_svg/issues/33)

## 0.7.0

- **BREAKING** Correct erroneous `width` and `height` processing on the root
  element.
  - Previously, `width` and `height` were treated as synonyms for the width and
    height of the `viewBox`. This is not correct, and resulted in meaningful
    rendering errors in some scenarios compared to Chrome. Fixing this makes the
    parser more conformant to the spec, but may make your SVGs look
    significantly different if they specify `width` or `height`. If you want the
    old behavior, you'll have to update your SVGs to not specify `width` and
    `height` (only specify `viewBox`).
- Use `MediaQuery.of(context).devicePixelRatio` if available before defaulting
  to `window.devicePixelRatio` in places that need awareness of
  devicePixelRatios.
- Support for `<use>`, `<symbol>`, and shape/group elements in `<defs>`. There
  are some limitations to this currently,

## 0.6.3

- Consume updated version of path_drawing.
- Fix bug with fill-rule inheritance + example to test.

## 0.6.2

- Consume updated version of path_drawing, which fixes
  [dnfield/flutter_svg#73](https://github.com/dnfield/flutter_svg/issues/73)

## 0.6.1

- Fixed an issue with stroke and fill inheritance (and added test)
- General formatting/analyzer cleanup

## 0.6.0

- **BREAKING** Update Flutter version dependencies/package dependencies
- Print unhandled errors only once, and only in debug mode (000e17f)
- Add ability to specify a `BoxFit` and `Alignment` for SvgPictures (Thanks
  @sroddy!).
- Support `userSpaceOnUse` gradientUnits (@sroddy)
- Miscellaneous bug fixes
- Restructure project to match expectations of Flutter tooling

## 0.5.5

- Create a new class to encapsulate `Paint` and assist with inheriting all
  painting properties.
- Fixes regression introduced in v0.5.2 where some previously working
  inheritance stopped working.
- Support more complex stroke/fill property inheritance.

## 0.5.4

- Consume latest path_drawing (and path_parsing) packages to fix issue(s) with
  smooth curve handling.

## 0.5.3

- Revert `HttpStatus.OK` change - not ready yet for Flutter beta channel

## 0.5.2

- Fix bug(s) in processing stroke and fill opacity when stroke/fill are
  inherited.
- Fix HTTP network headers for network pictures

## 0.5.1

- Consume latest change from path_drawing (fixes exponent validation)

## 0.5.0

- Minimum Flutter version is now 0.5.1 (latest beta as of release)
  - Merge in support for Focal Pointed Radial Gradients
  - Use asset directory references in pubspec.yaml
- Better support for nested `<tspan>` styles
- Support for `text-anchor` attribute
- Fix `<ellipse>` parsing bug (ellipses were drawn at half the expected size)
- Fix `<polyline>` parsing bug (polylines were incorrectly forced to be closed)

## 0.4.1

- Fix bug where widget caused exception in a `FittedBox`

## 0.4.0

- Added `width` and `height` properties to `SvgPicture`
- Remove deprecated code related to `SvgImage`
- Improved reporting of error conditions
  - Unsupported style elements will report an error
  - Unresolvable definitions will report an error
- Fixed `matchesTextDirection`
- Support for `text-anchor`

## 0.3.3

- Fix centering/scaling of canvas when viewBox is not square
- Improved color parsing

## 0.3.2

- Bug fix around caching for tinting/coloring (color was not being properly
  included in cache keys)

## 0.3.1

- Support for tinting/coloring the output
- Documentation updates

## 0.3.0

- This version represents a major rewrite of the widget(s) involved in rendering
  SVG drawings. This is primarily to support caching and better performance in
  rendering.
- New method on DrawableRoot toPicture to create a ui.Picture object from the
  SVG.
- Support for caching of Pictures, similar to how framework caches images. This
  will eventually be configurable, but is not as of this release.

### BREAKING CHANGES

- BREAKING CHANGE: `SvgImage`, `AvdImage`, and `VectorDrawableImage` have been
  deprecated. They relied on methods that are less efficient than those now
  surfaced in `SvgPicture`.
- BREAKING CHANGE: Size is no longer passed to `SvgPicture` - its size is
  determined by parent size.
- BREAKING CHANGE: `clipToViewBox` is now called `allowDrawingOutsideViewBox`.
  It defaults to false. It should not ordinarily be set to true, as it can allow
  unexpected memory usage if your vector graphic tries to draw far outside of
  the viewBox bounds.
- BREAKING CHANGE: `SvgPicture` does not support custom `ErrorWidgetBuilder`s at
  this point in time. However, errors will be properly logged to the console.
  This is a result of improvements in the loading/caching of drawings.

## 0.2.0

- Fix bug(s) in inheritance (better rendering of Ghostscript_Tiger.svg)
- Support for `<clipPath>`s
- Refactoring of how gradients are handled to enable clipPaths
- Refactor of SVG shape -> path logic

## 0.1.4

- Fix bugs in `<radialGradient>` percentage handling.
- Add error widget on error.
- Add ability to specify error/placeholder widgets.
- Minor improvement on flutter logo SVG (add missing gradient).
- Improve docs, unit tests.

## 0.1.3

- Add more unit tests and rendering tests (!).
- Add top level flutter_svg.dart.
- Fix bugs found in transform matrix logic for skewX and skewY.
- Minor improvements in handling inheritance for PathFillType.
- Support gradient spread types (TileModes in Flutter).

## 0.1.2

- Bump to path_drawing 0.2.3 (fix arc defect).
- Handle 'none' in dasharray without throwing exception.
- Better handling of inheritance and 'none' in fill/stroke/dasharray

## 0.1.1

- Handle opacity on groups and inherited/blended opacity.
- Fixes elements that have both opacity and stroke-opacity or fill-opacity.
- Improvements for inheritance.
- Fixes related to unspecified fills on shapes.

## 0.1.0

Bumping minor version due to internal breaking changes and new support. Works on
dev channel as of release (Flutter >= 0.3.6).

- Refactor `DrawableRoot` to support top level style definition.
- Support for dash paths.
- Support for more inherited attributes.
- Initial support for `@style` attributes.
- Support for `rgb()` color attribute/styles.
- Change painting order from stroke first, then fill to fill first, then stroke
  (matches Chrome rendering of `assets/simple/style_attr.svg`).

## 0.0.2

Initial text support.  Relies on flutter 0.3.6.

## 0.0.1

Initial release.  Relies on pre-released master.