React Native Circle Layout

Easily create any kind of a circular display of components - complete circle, semi-circle, quarter of a circle, or anything in between. Start anywhere, end anywhere. Animations? They're supported too. (Make sure you have the latest version.)

Don't sit to re-invent the wheel, doing all the math, when you can use react-native-circle-layout.

This library does the calculations to figure out where exactly it needs to place your elements so that they will be in a circular layout. Only minimal inputs required. See this section for all inputs, and their defaults.

What each element is going to be is left to you - it can be an icon, a button, an image, literally anything.

Star the project to show your support if you liked it!

Share your project in the discussions!

Installation

The published library works with the React Native stack used by the package, and the example/ app is pinned to React 19.2.3. That example intentionally uses React 19 APIs such as context provider shorthand and use.

npm install react-native-circle-layout

or

yarn add react-native-circle-layout

or

pnpm add react-native-circle-layout

Usage

import { CircleLayout } from 'react-native-circle-layout';

const Example = () => {
  const components = [];
  for (let i = 0; i < 6; i++) {
    components.push(
      <View style={{ alignItems: 'center' }}>
        <View style={styles.circleLayoutComponent} />
        <Text>Point {i}</Text>
      </View>
    );
  }

  return <CircleLayout components={components} radius={100} />;
};

Props

components Required

type: ReactNode[]

description: List of components that need to be placed on the circle.

radius Required

type: number

description: The radius of the circle.

centerComponent

type: ReactNode

description: The component to be shown at the center of the circle

sweepAngle

type: number

default value: 2 * Math.Pi

description: The distance in radians to be covered by the circle's arc from the starting point. This value should always be in radians between -2 * Math.PI and 2 * Math.PI.

For example, if the elements need to be placed in semi-circle the value will be Math.PI, for quarter of a circle, it will be Math.PI / 2.

startAngle

type: number

default value: 0

description: The angle at which the first component will be placed. The value needs to be in radians between -2 * Math.PI and 2 * Math.PI.

containerStyle

type: ViewStyle

description: The styling to be applied to the container of the component.

centerComponentContainerStyle

type: ViewStyle

description: The styling to be applied to the container of the center component.

animationProps

type: AnimationProps

description: The properties to configure the entry and exit animation of the component.

bgConfig

type: BgConfig

default value: undefined

description: The configuration for the background sectors drawn behind each component on the circle. If this prop is not provided, then no background is shown.

Methods

These methods are available via the ref prop on CircleLayout.

const ref = useRef<CircleLayoutRef>(null);
<CircleLayout ref={ref} components={components} radius={100} />

ref.current?.showComponents();
ref.current?.hideComponents();

showComponents()

Makes all circle-layout components visible. Triggers the entry animation on each component if animationProps is configured.

hideComponents()

Hides all circle-layout components. Triggers the exit animation on each component if animationProps is configured.

Custom Types and Constants

AnimationProps

export type AnimationProps = {
  /**
   * The configuration for the animation. The key of the record is the type of
   * animation and the value is the configuration for that animation. If a
   * particular animation type is not provided, then that animation will not
   * be performed.
   *
   * The order of the animation is determined by the key order of the object.
   */
  animationConfigs: Partial<Record<AnimationType, AnimationConfig>>;
  /**
   * The type of composition animation to be performed with
   * all the animation configs provided.
   *
   * For those composition which perform animation in a particular order,
   * the order is picked by the key order of the animationConfigs object.
   */
  animationCombinationType: AnimationCombinationType;
  /**
   * The gap between the start of animation of 2 consecutive components.
   * This value is in milliseconds.
   */
  animationGap?: number;
};

// Example
{
  animationConfigs: {
    [AnimationType.OPACITY]: {
      duration: 500,
      easing: Easing.inOut(Easing.ease),
    },
    [AnimationType.LINEAR]: {
      duration: 500,
    },
  },
  animationCombinationType: AnimationCombinationType.PARALLEL,
}

AnimationConfig

/**
 * The configuration for the animation.
 * @see https://reactnative.dev/docs/animated#timing
 */
export type AnimationConfig = Omit<
  Animated.TimingAnimationConfig,
  'toValue' | 'useNativeDriver'
>;

AnimationType

export enum AnimationType {
  /**
   * The component will fade in on entry and fade out on exit.
   */
  OPACITY = 'opacityAnimationConfig',
  /**
   * The component will move from the center to its final position.
   */
  LINEAR = 'linearAnimationConfig',
  /**
   * The component will move along the circumference of the circle
   * from the position of the first component to its final position.
   */
  CIRCULAR = 'circularAnimationConfig',
}

AnimationCombinationType

export enum AnimationCombinationType {
  /**
   * The animations will be performed in parallel.
   */
  PARALLEL = 'parallel',
  /**
   * The animations will be performed in sequence.
   */
  SEQUENCE = 'sequence',
}

BgConfig

export type BgConfig = {
  /**
   * The fill color for the background of the circle layout.
   * @default '#3d19e0'
   */
  color?: string;
  /**
   * The stroke color for the divider lines in the background.
   * @default color
   */
  strokeColor?: string;
  /**
   * The width of the stroke for the divider lines in the background.
   * @default 1
   */
  strokeWidth?: number;
  /**
   * The radius of the inner circle in the background.
   *
   * If this prop is not provided, the background is a filled circle with
   * the radius provided in CircleLayoutProps. If provided, the background
   * is a donut shape between innerRadius and the outer radius.
   * @default 0
   */
  innerRadius?: number;
  /**
   * The radius of the outer circle in the background.
   * @default radius provided in CircleLayoutProps
   */
  outerRadius?: number;
};

Authors

• @sonalip9

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

You can report bugs or request a feature on GitHub.

License

MIT

Made with create-react-native-library