React-Planet: Build Circular Navigation Menus (Setup & Examples)

A concise, practical guide to react-planet — a React circular UI component for orbital navigation, floating menus, and animated radial menus.

Overview — What react-planet does and why it matters

React-Planet is a React component that renders children in a circular (orbital) layout around a central trigger. It’s designed to create floating menus, radial tool palettes, and circular navigation UIs that expand from a central point. The concept maps naturally to mobile FAB menus, in-app quick-access toolbars, and creative dashboards.

From a UX perspective, circular navigation reduces screen real estate and provides a clear spatial relationship between actions. react-planet abstracts positioning math (angles, radii, offsets) and provides animation hooks so you can focus on the user flow rather than trigonometry. The component typically exposes props for radius, startAngle, animation timing, and open/close control.

If you need a compact, engaging navigation component for React — whether for a web app, PWA, or experimental UI — react-planet is a low-friction way to add orbital navigation that feels modern and playful without reinventing the wheel.

Installation & setup (quick start)

Getting started with react-planet is straightforward: install the package, import it, and render items as children. The component expects elements (buttons, links, icons) as children and handles layout and animation. You can toggle the open state and pass callbacks for item actions.

Install with your package manager, then import in your component file. If you prefer a step-by-step walkthrough, this practical write-up offers an end-to-end example: building circular navigation menus with react-planet.

• npm: npm install react-planet
• yarn: yarn add react-planet

After installation, wrap the menu items inside the <ReactPlanet /> component. Use state to control open/close and wire handlers to each child. This approach keeps the component stateless regarding item behavior while centralizing layout and animation within react-planet.

Core concepts and API you need to know

The core props to understand are radius (distance from center), startAngle (where the first item appears), rotation, and animation durations. Together these determine item placement around the circle and the feel of the orbital animation. Some implementations also support itemRadius, centerOffset, and expandDirection to control orientation.

react-planet typically operates by positioning children absolutely within a relative container and animating transform/opacity on open. That means you can layer CSS transitions or requestAnimationFrame-based tweens on top if you need custom easing curves. Event callbacks like onOpen, onClose, and onClickItem let you intercept interactions and trigger app logic.

Common props and behaviors to look for (or implement) are: controlled open state, keyboard navigation support, aria attributes for screen readers, and configuration for how children are ordered. Below is a compact list of the most-used props to check in your version:

• radius — how far items orbit from the center
• startAngle — initial angle in degrees
• animationDuration — open/close animation time
• open — controlled boolean to expand/collapse

Customization, animations, and practical example

Customize look and behavior with CSS and props: change item size, swap icons, adjust spacing, or add shadows for depth. For animations, prefer transform and opacity transitions for best performance; use translate/rotate to keep animations GPU-accelerated. You can chain staggered delays to create orbital waves or spring physics for a bouncy entrance.

Below is a minimal React example showing react-planet usage. It demonstrates install, state handling, and item callbacks. Replace icons with your own SVGs or components to match your UI design system.

import React, { useState } from 'react';
import ReactPlanet from 'react-planet';

export default function PlanetMenu() {
  const [open, setOpen] = useState(false);
  return (
    <div style={{ position:'relative', width:200, height:200 }}>
      <ReactPlanet
        open={open}
        radius={70}
        startAngle={-90}
        animationDuration={300}
      >
        <button onClick={(e)=>console.log('A')}>A</button>
        <button onClick={(e)=>console.log('B')}>B</button>
        <button onClick={(e)=>console.log('C')}>C</button>
      </ReactPlanet>
      <button onClick={()=>setOpen(v => !v)} aria-label="Toggle menu">Menu</button>
    </div>
  );
}

This example shows a central toggle outside the planet container. You can also make the central node a child of react-planet so it rotates with items or acts as the anchor. For complex UIs, combine react-planet with context/state managers to coordinate item states and permissions.

Accessibility, performance, and best practices

Orbital menus can be visually striking but must still follow accessibility guidelines. Ensure each actionable child has a semantic element (button or link), meaningful aria-labels, and a focusable order. Implement keyboard open/close (Space/Enter/Escape) and arrow-key navigation if you have many items. Screen reader users benefit from announcing the open/closed state and the number of items.

For performance, animate transform and opacity instead of top/left. Keep the number of simultaneous animated elements reasonable; more than 8–10 animated children can tax low-end devices. Use CSS will-change sparingly and remove heavy box-shadows or costly filters that degrade frame rates on mobile.

Testing across viewports matters: radial layout on narrow screens may require different radii or orientation (semi-circle instead of full circle). Provide fallbacks — a simple stacked list or toolbar — for constrained environments or user preferences that disable motion.

Troubleshooting and common gotchas

If items overlap or clip, check container sizing and overflow settings. React-planet positions children absolutely — you need a relative parent with sufficient width/height for the calculated orbit. If you see jittery motion, ensure CSS transforms are used and that you don’t have conflicting transitions on position properties.

Another common issue is event propagation: when the central toggle is inside the planet, clicks can trigger both toggle and item handlers. Use stopPropagation where needed and design a clear hit area for the central control. Also verify that z-index stacking is correct when layering the menu above other UI elements.

Finally, compatibility with SSR: if your app renders on the server, guard client-only layout calculations with checks (window/document) or perform initial render in a compact fallback mode until hydration completes. This avoids mismatch warnings and layout flashes.

Where to learn more and reference links

For a hands-on tutorial and step-by-step demo, check this practical guide on building circular navigation menus with react-planet: building circular navigation menus with react-planet. It walks through setup, examples, and code snippets that complement this guide.

You can also install the package from the official NPM registry: react-planet on npm. The package page includes version history, download stats, and links to source repositories where you can inspect props and issues.

When integrating into production apps, treat react-planet as a UI primitive — adapt styles and behavior to fit accessibility, internationalization (RTL), and responsive design requirements.

FAQ

What is react-planet and when should I use it?

react-planet is a React component for creating radial or circular navigation menus. Use it when you want a compact, visually distinct navigation (floating or orbital menus) that conserves space and groups related actions around a central trigger.

How do I install and set up react-planet?

Install with npm install react-planet or yarn add react-planet. Import the component, render children as menu items, and control the open state via React state. Set props like radius, startAngle, and animationDuration to tune layout and motion.

How can I customize animations and ensure accessibility?

Customize animationDuration and easing through props or CSS. Use transform/opacity transitions for performance and staggered delays for polish. For accessibility, ensure buttons have aria-labels, support keyboard navigation, and manage focus when the menu opens or closes.