rn-linear-gradient

A drop-in replacement for react-native-linear-gradient and expo-linear-gradient that uses React Native's built-in experimental_backgroundImage (Android/iOS) and backgroundImage (Web) style properties.

No native module. No pod install. No Expo dependency required.

Why?

react-native-linear-gradient requires native linking and pod install. expo-linear-gradient requires Expo infrastructure. This library delivers the same public API using only React Native's built-in gradient support, available since RN 0.73.

Requirements

| Peer | Version | | -------------- | -------- | | react-native | ≥ 0.73 | | react | ≥ 17 |

React Native's experimental_backgroundImage was introduced in 0.73 (Android & iOS). Web uses the standard backgroundImage style property.

Installation

npm install rn-linear-gradient
# or
yarn add rn-linear-gradient

No pod install or native linking needed.

Migration

Change one line — your import:

# react-native-linear-gradient
- import LinearGradient from 'react-native-linear-gradient';
+ import { LinearGradient } from 'rn-linear-gradient';

# expo-linear-gradient
- import { LinearGradient } from 'expo-linear-gradient';
+ import { LinearGradient } from 'rn-linear-gradient';

Everything else stays exactly the same.

Note: rn-linear-gradient also ships a default export, so import LinearGradient from 'rn-linear-gradient' works too.

Usage

import { StyleSheet, Text, View } from "react-native";
import { LinearGradient } from "rn-linear-gradient";

export default function App() {
  return (
    <View style={styles.container}>
      {/* Background overlay */}
      <LinearGradient
        colors={["rgba(0,0,0,0.8)", "transparent"]}
        style={styles.background}
      />

      {/* Gradient button */}
      <LinearGradient
        colors={["#4c669f", "#3b5998", "#192f6a"]}
        style={styles.button}
      >
        <Text style={styles.text}>Sign in with Facebook</Text>
      </LinearGradient>

      {/* Angle-based gradient */}
      <LinearGradient
        colors={["#ff6b6b", "#feca57"]}
        useAngle
        angle={135}
        style={styles.button}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, alignItems: "center", justifyContent: "center" },
  background: { position: "absolute", left: 0, right: 0, top: 0, height: 300 },
  button: { padding: 15, alignItems: "center", borderRadius: 5 },
  text: { fontSize: 15, color: "#fff" },
});

API

<LinearGradient>

| Prop | Type | Required | Default | Description | | -------------- | ---------------------------------------------------- | -------- | --------------------- | ---------------------------------------------------------------------------------------------------- | | colors | readonly [ColorValue, ColorValue, ...ColorValue[]] | ✅ | — | At least two gradient color stops | | locations | readonly [number, number, ...number[]] \| null | — | Evenly spaced | Stop positions (0–1), same length as colors | | start | { x: number; y: number } \| [x, y] \| null | — | { x: 0.5, y: 0 } | Gradient start point (fraction of view size). Ignored when useAngle is true. | | end | { x: number; y: number } \| [x, y] \| null | — | { x: 0.5, y: 1 } | Gradient end point (fraction of view size). Ignored when useAngle is true. | | useAngle | boolean | — | false | When true, use angle instead of start/end for direction | | angle | number | — | 0 | Gradient angle in degrees, clockwise from top (same as CSS). Only used when useAngle is true. | | angleCenter | { x: number; y: number } | — | { x: 0.5, y: 0.5 } | Accepted for API compatibility. Only has the expected effect at the default value (CSS limitation). | | dither | boolean | — | true | Accepted for API compatibility; has no effect (RN handles dithering natively). | | ...ViewProps | — | — | — | All standard View props are forwarded |

Types

import type {
  LinearGradientProps,
  LinearGradientPoint,
  NativeLinearGradientPoint,
} from "rn-linear-gradient";

How it works

The component converts start/end coordinates into a CSS angle using:

angle = atan2(dx, dy)   // clockwise from top — same convention as CSS

Or when useAngle is true, uses the angle directly. Then it builds a linear-gradient(Ndeg, color1 stop%, ...) string and applies it as:

• experimental_backgroundImage on Android & iOS
• backgroundImage on Web

Caveats

• Requires RN ≥ 0.73. The experimental_backgroundImage prop didn't exist before that.
• The experimental_ prefix means the API could change in a future RN release. This library will track those changes.
• angleCenter has no effect when set to a non-default value — CSS linear-gradient always anchors to the element center.
• Unlike react-native-linear-gradient, this library does not use a native view — it relies entirely on the style system, with the same rendering capabilities and limits as CSS gradients.

License

MIT