Getting started

Welcome to AgDS - the Design System for the Australian Government Department of Agriculture, Fisheries and Forestry. In this guide we are going to go through the steps necessary to get started with the React component library from our Design System.

What is React?

Our component library is built with React, a popular JavaScript library for building User Interfaces.

If you’re new to React, we recommend going through the official React getting started documentation.

If you’re starting a new project…

For new projects, we recommend using Next.js. A new application can be scaffolded with npx create-next-app@latest. Read their docs for more information.

Install dependencies

The following dependencies will need to be installed:

@ag.ds-next/react
@emotion/cache
@emotion/react

Add support for Emotion

Our component library uses the CSS-in-JS styling library, Emotion. While in-built support for Next.js’s App Router is still in progress, you can add support now with a custom RootStyleRegistry.

Create the following component in src/components/RootStyleRegistry/index.tsx.

'use client';

import { CacheProvider } from '@emotion/react';
import createCache from '@emotion/cache';
import { useServerInsertedHTML } from 'next/navigation';
import { JSX, useState } from 'react';

export const RootStyleRegistry = ({ children }: { children: JSX.Element }) => {
	const [{ cache, flush }] = useState(() => {
		const cache = createCache({ key: 'css' });
		cache.compat = true;
		const prevInsert = cache.insert;
		let inserted: string[] = [];
		cache.insert = (...args) => {
			const serialized = args[1];
			if (cache.inserted[serialized.name] === undefined) {
				inserted.push(serialized.name);
			}
			return prevInsert(...args);
		};
		const flush = () => {
			const prevInserted = inserted;
			inserted = [];
			return prevInserted;
		};
		return { cache, flush };
	});

	useServerInsertedHTML(() => {
		const names = flush();
		if (names.length === 0) return null;
		let styles = '';
		for (const name of names) {
			styles += cache.inserted[name];
		}
		return (
			<style
				data-emotion={`${cache.key} ${names.join(' ')}`}
				dangerouslySetInnerHTML={{
					__html: styles,
				}}
			/>
		);
	});

	return <CacheProvider value={cache}>{children}</CacheProvider>;
};

3. Create an App component to wrap your application

The RootStyleRegistry and Core components needs to wrap your entire application. Core is where you can configure the theme and routing/links. For an example of configuring routing/links in AgDS for a Next.js application, please see the code for our example site.

/** @jsxImportSource @emotion/react */
'use client';

import { type ReactNode } from 'react';
import { theme } from '@ag.ds-next/react/ag-branding';
import { Core } from '@ag.ds-next/react/core';
// Note: You will need to create this import
import { LinkComponent } from '../LinkComponent';
import { RootStyleRegistry } from '../RootStyleRegistry';

export const App = ({ children }: { children: ReactNode }) => {
	return (
		<RootStyleRegistry>
			<Core linkComponent={LinkComponent} theme={theme}>
				{children}
			</Core>
		</RootStyleRegistry>
	);
};

Then import this into the root layout.tsx.

export default function RootLayout({
	children,
}: Readonly<{
	children: ReactNode;
}>) {
	return (
		<html lang="en">
			<body>
				<App>{children}</App>
			</body>
		</html>
	);
}

That’s it

You can now start using AgDS!

We recommend using TypeScript to get the most out of these components. Our example site already uses TypeScript so you can use that as reference. See code.

What’s next?

Explore our example site to see our list of interface examples, as well as the related code on GitHub.

You should also explore our wide range of components, and install the ones you need in your application.

Edit this page