Your premier destination for quality journalism, breaking news, and in-depth stories — powered by real-time APIs.
- Overview
- Screenshots
- Tech Stack
- API Integrations
- Project Structure
- Core Features
- Getting Started
- Privacy & Data
- Roadmap
- Developer
Headline is a modern, API-driven news aggregation platform that combines journalistic excellence with cutting-edge web technology. All articles are dynamically fetched from trusted third-party APIs, ensuring content is always fresh, diverse, and accurate.
Key highlights:
- 🌍 Global coverage — news from thousands of sources via NewsData.io
- 📈 Market data — real-time financial news powered by Finnhub
- 🤖 AI-enhanced reading — clean article extraction via Jina AI Reader
- 🎨 Premium UX — dark/light themes, customizable reading settings, skeleton loaders
- 🔐 Privacy-first — fully client-side, no user data collected or stored
Disclaimer: Headline operates as a demonstration news platform. All articles and content are fetched from third-party APIs to illustrate the platform's capabilities. We do not claim ownership or editorial control over the displayed content.
| 🌙 Home — Dark | ☀️ Home — Light | ⏳ Skeleton — Dark | ⏳ Skeleton — Light |
 Dark mode home page |
 Light mode home page |
 Loading state — dark |
 Loading state — light |
| 📰 Article Reader | 🔍 Search | 🔎 Search Results | |
 Full article reader |
 Graceful load error |
 Search interface |
 Live search results |
| 🗂️ All Categories | 📁 Category Feed | 🔥 Trending | ℹ️ About / Privacy |
 Browse all categories |
 Articles by category |
 Trending stories |
 About & Privacy pages |
| Category | Tools & Libraries |
|---|---|
| Core Framework | React 19.2.0, TypeScript 5.9.3, Vite 7.3.1 |
| Styling | Tailwind CSS 4.1.18, shadcn/ui, Radix UI Primitives |
| Data Fetching | TanStack React Query 5.90 |
| Routing | React Router 7.13 |
| Animations | Motion 12.34 |
| Content Parsing | @mozilla/readability, DOMPurify, react-markdown |
| HTTP Client | Axios 1.13 |
| UI & Components | Lucide React Icons, Embla Carousel, Sonner Toasts |
| Theming | next-themes |
| Dev Tooling | ESLint 9, TypeScript ESLint, Vite HMR |
| API | Usage | Docs |
|---|---|---|
| NewsData.io | Global news from thousands of sources, with multi-key rotation support | newsdata.io/documentation |
| Finnhub | Real-time financial market data and business news | finnhub.io/docs |
| Jina AI Reader | AI-powered content extraction for clean, readable article text | jina.ai/reader |
src/
│
├── api/ # External API clients
│ ├── market/
│ │ ├── finnhubApi.ts # Finnhub market data fetcher
│ │ └── index.ts
│ ├── news/
│ │ ├── apiKeyManager.ts # Rotating API key manager (multi-key support)
│ │ ├── newsApi.ts # NewsData.io fetcher
│ │ └── index.ts
│ └── index.ts
│
├── components/
│ ├── shared/ # Reusable UI components
│ │ ├── ArticleCard.tsx # News card component
│ │ ├── CategoriesBar.tsx # Top categories navigation bar
│ │ ├── EmptyState.tsx # Empty / no-results state
│ │ ├── Footer.tsx
│ │ ├── ImageWithFallback.tsx # Image with error fallback
│ │ ├── Loader.tsx # Spinner loader
│ │ ├── LoadingState.tsx # Skeleton loading layout
│ │ ├── LogoIcon.tsx
│ │ ├── ModernBreakingNews.tsx # Animated breaking news ticker
│ │ ├── ModernHeader.tsx # Top navigation header
│ │ ├── NavigationDrawer.tsx # Mobile sidebar drawer
│ │ ├── NewsList.tsx # Article list renderer
│ │ ├── ScrollToTop.tsx # Floating scroll-to-top button
│ │ ├── SmartSearch.tsx # Live search with suggestions
│ │ └── TrendingList.tsx # Trending articles list
│ └── ui/ # shadcn/ui primitives
│ └── button.tsx
│
├── features/
│ ├── article/ # Article page features
│ │ ├── ColorPicker.tsx # Reading background color selector
│ │ ├── ReadingProgressBar.tsx # Scroll progress indicator
│ │ ├── ReadingSettingsPanel.tsx # Font, size & layout settings
│ │ └── ShareButtons.tsx # Social share + copy link buttons
│ └── home/ # Home page sections
│ ├── CategoryShowcase.tsx
│ ├── CompactMarketWatch.tsx # Mini market ticker strip
│ ├── EliteCategorySection.tsx
│ ├── FeaturedCarousel.tsx # Hero news carousel
│ └── LatestNewsSection.tsx
│
├── hooks/ # Custom React hooks
│ ├── useCategoryArticleCounts.ts
│ ├── useJinaContent.ts # Fetch & parse article via Jina
│ ├── usePageLoading.ts
│ ├── useReadingSettings.ts # Persist reading preferences
│ ├── useUserCity.ts # Detect user location
│ └── index.ts
│
├── layouts/
│ └── RootLayout.tsx # App shell with header & footer
│
├── lib/
│ ├── query/ # TanStack Query configuration
│ │ ├── market/ # Market query hooks & constants
│ │ ├── news/ # News query hooks, keys, filters
│ │ ├── queryClient.ts
│ │ └── QueryProvider.tsx
│ ├── theme/ # Theme context & provider
│ ├── categories-data.ts # Static category definitions
│ ├── dateUtils.ts
│ ├── localCache.ts # localStorage caching helpers
│ ├── mock-data.ts
│ ├── reading-settings.ts
│ ├── reading-settings-context.tsx
│ └── utils.ts
│
├── pages/ # Route-level page components
│ ├── AboutPage.tsx
│ ├── ArticlePage.tsx
│ ├── CategoriesPage.tsx
│ ├── CategoryPage.tsx
│ ├── HomePage.tsx
│ ├── NotFoundPage.tsx # 404 page
│ ├── PrivacyPage.tsx
│ ├── SearchPage.tsx
│ ├── TrendingPage.tsx
│ └── index.ts
│
├── routes/
│ └── index.ts # Centralized route definitions
│
├── services/
│ └── articleExtractor.ts # Jina Reader extraction service
│
├── styles/
│ ├── fonts.css
│ └── globals.css
│
├── types/ # Shared TypeScript types
│ ├── article.ts
│ ├── market.ts
│ ├── news.ts
│ └── index.ts
│
├── utils/
│ └── variants.ts # CVA class variant utilities
│
├── App.tsx # Root component & router setup
├── main.tsx # App entry point
└── vite-env.d.ts
- Real-time articles fetched from multiple news APIs
- Breaking news ticker with smooth animated scroll
- Featured hero carousel showcasing top stories
- Category filtering — browse articles by topic
- Trending stories — discover what's popular right now
- Smart search with live suggestions
- AI-powered content extraction via Jina Reader for clean, distraction-free reading
- Reading progress bar that tracks your scroll position through the article
- Customizable reading panel — adjust font size, background color, and layout; all preferences are saved to
localStorage - Share buttons — Facebook, Twitter, LinkedIn, and Copy Link
- Graceful error fallback when an article cannot be extracted
- Compact market ticker on the home page with live stock and financial data powered by Finnhub
- Dark / Light mode with persistent user preference
- Skeleton loading states for smooth perceived performance
- Fully responsive — optimized for mobile, tablet, and desktop
- Mobile navigation drawer for smaller screens
- Scroll-to-top floating button
- Custom 404 page
- Built-in rotating API key manager — cycles through up to 3 NewsData.io keys automatically to prevent rate limiting
# Clone the repository
git clone https://github.com/your-username/Headline-News.git
cd Headline-News
# Install dependencies
npm installCreate a .env.local file in the root directory and fill in your API keys:
# ─── Finnhub ────────────────────────────────────────────────
# Get your free key at: https://finnhub.io
VITE_FINNHUB_API_KEY=""
# ─── NewsData.io ─────────────────────────────────────────────
# Get your free key at: https://newsdata.io
# Add 1 up to 5 keys — the app rotates between them automatically to avoid hitting rate limits
VITE_NEWSDATA_API_KEY_1="pub_"
VITE_NEWSDATA_API_KEY_2="pub_"
VITE_NEWSDATA_API_KEY_3="pub_"
# ─── Jina AI Reader ──────────────────────────────────────────
# Get your free key at: https://jina.ai/reader
VITE_JINA_READER_API_KEY="jina_"# Start development server
npm run dev
# Type-check and build for production
npm run build
# Preview production build
npm run preview
# Lint the codebase
npm run lintHeadline is a client-side only application. It does not:
- Collect personal information
- Use tracking cookies or analytics
- Store any data on external servers
The only data stored locally is your theme preference and reading settings, saved in your browser's localStorage. This data never leaves your device.
All news content is fetched in real time from third-party APIs and is displayed "as is." Headline does not independently verify, endorse, or take responsibility for the accuracy of any displayed content.
| Status | Feature |
|---|---|
| ✅ Done | Core news aggregation platform |
| ✅ Done | Dark/Light theme |
| ✅ Done | Customizable reading experience |
| ✅ Done | Market watch ticker |
| ✅ Done | AI-powered article extraction |
| 🔄 Planned | Dedicated stocks/market page |
| 🔄 Planned | Backend server for saving & bookmarking articles |
| 🔄 Planned | Functional article view count & engagement metrics |
| 🔄 Planned | Working social media share links per article |
| 🔄 Planned | Additional UI & performance improvements |
Maher Elmair
- 📫 maher.elmair.dev@gmail.com
- ✖️ X (Twitter)
- ❤️ Made with passion by Maher Elmair
🚀 Try it now on Vercel:
If you found this project useful or inspiring, please consider giving it a ⭐️
Pull requests, issues, and suggestions are always welcome 🙏