ajax
Creates an Observable that will perform an AJAX request using XMLHttpRequest. This is the most configurable option for making HTTP requests in RxJS.
Import
import { ajax } from 'rxjs/ajax';
Type Signature
function ajax<T>(config: AjaxConfig): Observable<AjaxResponse<T>>;
function ajax<T>(url: string): Observable<AjaxResponse<T>>;
// Helper methods
ajax.get<T>(url: string, headers?: Record<string, string>): Observable<AjaxResponse<T>>;
ajax.post<T>(url: string, body?: any, headers?: Record<string, string>): Observable<AjaxResponse<T>>;
ajax.put<T>(url: string, body?: any, headers?: Record<string, string>): Observable<AjaxResponse<T>>;
ajax.patch<T>(url: string, body?: any, headers?: Record<string, string>): Observable<AjaxResponse<T>>;
ajax.delete<T>(url: string, headers?: Record<string, string>): Observable<AjaxResponse<T>>;
ajax.getJSON<T>(url: string, headers?: Record<string, string>): Observable<T>;
Parameters
Either a configuration object or a URL string. When a string is provided, it performs a GET request.AjaxConfig properties:HTTP method (GET, POST, PUT, PATCH, DELETE, etc.)
HTTP headers to send with the request (case-insensitive)
Request body. Automatically serialized based on content-type
responseType
XMLHttpRequestResponseType
default:"json"
Expected response type: ‘json’, ‘text’, ‘blob’, ‘arraybuffer’, ‘document’
Timeout in milliseconds. 0 means no timeout
Whether to send credentials (cookies) with CORS requests
Whether this is a cross-domain request
Query parameters to append to the URL
Returns
Observable<AjaxResponse<T>>
An Observable that emits an AjaxResponse object containing:The original XMLHttpRequest object
The original request configuration
Description
The ajax operator creates an Observable for XMLHttpRequest-based AJAX calls. It provides a more reactive way to handle HTTP requests compared to traditional callbacks or promises.
Key features:
- Automatic JSON parsing
- Full TypeScript support
- Configurable headers, timeout, and credentials
- Progress events support
- Proper error handling
- Cancellation via unsubscription
Examples
Basic GET Request
import { ajax } from 'rxjs/ajax';
import { map, catchError, of } from 'rxjs';
const users$ = ajax('https://api.github.com/users?per_page=5').pipe(
map(response => response.response),
catchError(error => {
console.error('Error:', error);
return of([]);
})
);
users$.subscribe(users => console.log('Users:', users));
POST Request with Body
import { ajax } from 'rxjs/ajax';
const createUser$ = ajax({
url: 'https://api.example.com/users',
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer token123'
},
body: {
name: 'John Doe',
email: 'john@example.com'
}
});
createUser$.subscribe({
next: response => console.log('Created:', response.response),
error: err => console.error('Error:', err)
});
Using Helper Methods
import { ajax } from 'rxjs/ajax';
// Returns Observable<User[]> directly (not wrapped in AjaxResponse)
const users$ = ajax.getJSON<User[]>('https://api.example.com/users');
users$.subscribe(users => console.log(users));
With Query Parameters
import { ajax } from 'rxjs/ajax';
const search$ = ajax({
url: 'https://api.example.com/search',
queryParams: {
q: 'rxjs',
limit: 10,
offset: 0
}
});
// Requests: https://api.example.com/search?q=rxjs&limit=10&offset=0
With Timeout
import { ajax } from 'rxjs/ajax';
import { catchError, of } from 'rxjs';
const request$ = ajax({
url: 'https://api.example.com/slow-endpoint',
timeout: 5000 // 5 seconds
}).pipe(
catchError(error => {
if (error.name === 'AjaxTimeoutError') {
console.error('Request timed out');
}
return of({ response: null });
})
);
Cancellable Request
import { ajax } from 'rxjs/ajax';
const request$ = ajax('https://api.example.com/data');
const subscription = request$.subscribe(
response => console.log(response.response)
);
// Cancel the request after 1 second
setTimeout(() => {
subscription.unsubscribe();
console.log('Request cancelled');
}, 1000);
Common Use Cases
REST API Client
import { ajax } from 'rxjs/ajax';
import { map } from 'rxjs/operators';
class ApiClient {
private baseUrl = 'https://api.example.com';
get<T>(endpoint: string) {
return ajax.getJSON<T>(`${this.baseUrl}${endpoint}`);
}
post<T>(endpoint: string, body: any) {
return ajax.post(`${this.baseUrl}${endpoint}`, body).pipe(
map(response => response.response as T)
);
}
delete(endpoint: string) {
return ajax.delete(`${this.baseUrl}${endpoint}`);
}
}
const api = new ApiClient();
api.get<User[]>('/users').subscribe(users => console.log(users));
Polling with Error Handling
import { ajax } from 'rxjs/ajax';
import { interval, switchMap, retry, catchError, of } from 'rxjs';
const poll$ = interval(5000).pipe(
switchMap(() => ajax.getJSON('/api/status')),
retry(3),
catchError(error => {
console.error('Polling failed:', error);
return of({ status: 'unknown' });
})
);
poll$.subscribe(status => console.log('Status:', status));
Error Handling
The ajax operator emits errors for:
- Network failures
- HTTP status codes 4xx and 5xx
- Timeout (AjaxTimeoutError)
- Aborted requests (when unsubscribed)
import { ajax } from 'rxjs/ajax';
import { catchError, of } from 'rxjs';
ajax('https://api.example.com/data').pipe(
catchError(error => {
if (error.status === 404) {
console.error('Resource not found');
} else if (error.status === 500) {
console.error('Server error');
} else if (error.name === 'AjaxTimeoutError') {
console.error('Request timed out');
} else {
console.error('Network error:', error);
}
return of({ response: null });
})
).subscribe();
Tips
Use ajax.getJSON() when you only need the response body and don’t care about headers or status codes.
The ajax operator automatically aborts the XMLHttpRequest when you unsubscribe, preventing memory leaks.
CORS restrictions apply. Ensure your API server is configured to accept requests from your domain.
- from - Convert promises to Observables (can be used with fetch)
- fromEvent - Create Observables from events
- defer - Lazily create Observables
See Also
