Linear gradient
@symbiote-native/linear-gradient wraps
expo-linear-gradient, a native view
that paints a gradient behind its children, so every SymbioteNative adapter can reach it, not just
React. The props, the point normalization and the per-platform structure are written once and
shared by all five adapters.
Installation
Section titled “Installation”npm install @symbiote-native/linear-gradientScaffolding or extending a SymbioteNative app? npx @symbiote-native/cli new --linear-gradient (or
add --linear-gradient in an existing app) installs and wires this for you.
import { LinearGradient } from '@symbiote-native/linear-gradient/react';
<LinearGradient colors={['#4c669f', '#192f6a']} start={{ x: 0, y: 0 }} end={[1, 1]}> <Text>Over the gradient</Text></LinearGradient>;<script setup lang="ts">import { LinearGradient } from '@symbiote-native/linear-gradient/vue';</script>
<template> <LinearGradient :colors="['#4c669f', '#192f6a']" :end="[1, 1]"> <text>Over the gradient</text> </LinearGradient></template><script lang="ts"> import { LinearGradient } from '@symbiote-native/linear-gradient/svelte';</script>
<LinearGradient colors={['#4c669f', '#192f6a']} end={[1, 1]}> <text>Over the gradient</text></LinearGradient>import { LinearGradient } from '@symbiote-native/linear-gradient/solid';
<LinearGradient colors={['#4c669f', '#192f6a']} end={[1, 1]}> <text>Over the gradient</text></LinearGradient>;import { LinearGradient } from '@symbiote-native/linear-gradient/angular';
@Component({ imports: [LinearGradient], template: `<LinearGradient [colors]="colors" [end]="[1, 1]"><text>Over the gradient</text></LinearGradient>`,})export class Card { readonly colors = ['#4c669f', '#192f6a'];}| Prop | Description |
|---|---|
colors |
Two or more colors. For one color use style.backgroundColor |
locations |
Stops from 0 to 1, ascending, same length as colors |
start |
{ x, y } or [x, y], default { x: 0.5, y: 0 } |
end |
{ x, y } or [x, y], default { x: 0.5, y: 1 } |
dither |
Android only, default on |
Plus style, testID, nativeID, onLayout and the accessibility and responder props every View
takes. Not ported: the web variant.
- Children go inside the gradient. It paints behind them. On iOS the native gradient is the root
view. On Android the root is a plain
Viewthat carries yourstyle, with the native gradient filling it as a child, sochildren,onLayoutand touches behave as on anyView. - Rounded corners go in
style.borderRadiusand the four per-corner radii are read fromstyleand handed to the native gradient, because React Native does not clip a native view by a radius on its own. - A bad value warns instead of throwing. A
startorendthat is not[x, y]or{ x, y }is ignored, and alocationsarray of the wrong length is cut to the number ofcolors. Both log a warning and the gradient still draws. colorstakes anythingstylecolors take. Names, hex,rgb()/rgba()andhsl()all go through the same color processing as every other view.- Where the native view is missing, you get a plain
View. The package logsLinearGradient is not available on this platformand renders your children without a gradient.
Common questions
Section titled “Common questions”transparent to white (or any color) looks gray on iOS. Apple platforms interpolate
transparent as transparent black, so the middle of the fade turns gray. Fade to a transparent
version of the exact color instead: ['rgba(255, 255, 255, 0)', '#ffffff'] rather than
['transparent', '#ffffff']. Android shows the same gradient either way, which is why the problem
only appears on iOS.
The gradient looks different on iOS and Android. Check start and end first. Setting both to
the same point describes no direction at all, and that case is reported to render differently on the
two platforms. Give them distinct points, for example start={{ x: 0, y: 0 }} and
end={{ x: 1, y: 1 }} for a diagonal.
How do I get rounded corners? Put borderRadius (or borderTopLeftRadius and the other three)
in style, a class or a StyleSheet. On Android the radii are passed to the native gradient by hand
and on iOS the root view applies them.
Can I fill text with a gradient? Not with this package alone. The usual recipe masks a gradient
with the text using @react-native-masked-view/masked-view, a third-party React Native component,
so it runs only under the React adapter. SymbioteNative ships no masked view for Vue, Svelte, Solid
or Angular. On Android the masked view needs a recent release: older ones showed a solid color
instead of the gradient.
How do I animate the colors? colors is an ordinary prop, so drive it from state, a signal or a
rune and the gradient repaints. Do not expect a smooth tween that way: each change is a native view
update, and reports of animating colors through Reanimated’s animatedProps show it working on iOS
and not on Android. For a fade between two looks, stack two gradients and animate the opacity of
the top one.
Is it slow in a long list? One gradient is cheap, many of them are not. A startup slowdown on
Android was fixed upstream in SDK 49, but scrolling lists with a gradient in every row is still
reported to stutter. Draw the gradient once behind the list rather than per row, keep the number
that are on screen small, and try dither={false} on Android, which upstream says may speed up
rendering at the cost of visible banding.
Why does colors need two entries? A gradient needs two stops. For a single color set
style.backgroundColor on a View.
Sources:
- Expo docs: LinearGradient
- expo/expo#7418 LinearGradient transparent to white is wrong on iOS
- CSS-Tricks: what to know about gradients toward transparent black
- expo/expo#25595 start and end mismatch between iOS and Android
- expo/expo#32934 LinearGradient with MaskedView on Android
- expo/expo#29408 animating colors with Reanimated on Android
- expo/expo#23861 renders very slow on Android
How the wrapper works
Section titled “How the wrapper works”expo-linear-gradient’s JS is hand-ported into this package’s core/: the props type, point
normalization, locations check and the per-platform descriptor. renderLinearGradient returns one
descriptor and each adapter only turns it into its own element, so the five adapters cannot drift
apart. The native view is registered when the first gradient renders, through
requireNativeViewManager, and the engine derives its events and prop processors from that
registration. The native code is never vendored: expo-modules-autolinking resolves it from
node_modules (see the native setup guide).