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