TypeScript icon, indicating that this package has built-in type declarations

    1.0.0Β β€’Β PublicΒ β€’Β Published


    Published on npm Published on webcomponents.org ISC License Release

    πŸ‘Ύ Atomico Hooks for Apollo GraphQL πŸš€

    View Live Demo

    πŸ”Ž Read the Full API Docs πŸ”Ž

    πŸ““ Contents

    πŸ”§ Installation

    Apollo Elements atomico hooks are distributed through npm, the node package manager. To install a copy of the latest version in your project's node_modules directory, install npm on your system then run the following command in your project's root directory:

    npm install --save @apollo-elements/atomico

    πŸ‘©β€πŸš€ Usage

    See our docs on setting up Apollo client so your components can fetch their data.

    This package provides useMutation, useQuery, and useSubscription hooks.

    ❓ Queries

    Query data with the useQuery hook.

    First, let's define our component's GraphQL query.

    query HelloQuery {
      helloWorld {

    Read our docs on working with GraphQL files during development and in production for more info, and be sure to read about generating TypeScript types from GraphQL to enhance your developer experience and reduce bugs.

    Next, we'll define our UI component with the useQuery hook. Import the hook and helpers, your query, and the types:

    import { useQuery, c } from '@apollo-elements/atomico';
    import { HelloQuery } from './Hello.query.graphql';
    declare global {
      interface HTMLElementTagNameMap {
        'hello-query': HTMLElement

    Then define your component's template function.

    function Hello() {
      const { data, error, loading } = useQuery(HelloQuery);
      const greeting = data?.helloWorld.greeting ?? 'Hello';
      const name = data?.helloWorld.name ?? 'Friend';
      const spinRef = useHost();
      useLayoutEffect(() => {
        spinRef.current.toggleAttribute('active', loading);
      }, [loading]);
      return (
          <what-spin-such-loader ref={spinRef}></what-spin-such-loader>
          <article id="error" hidden={!error}>
            <h2>😒 Such Sad, Very Error! 😰</h2>
          <p>{greeting}, {name}!</p>
    customElements.define('hello-query', c(Hello));

    πŸ‘Ύ Mutations

    Mutations are how you affect change on your graph. Define a mutation in graphql.

    mutation UpdateUser($username: String, $haircolor: String) {
      updateUser(username: $username, haircolor: $haircolor) {

    Then import useMutation and the atomico API along with your data types.

    import { useMutation, useState, c } from '@apollo-elements/atomico';
    import { UpdateUserMutation } from './UpdateUser.mutation.graphql';
    declare global {
      interface HTMLElementTagNameMap {
        'update-user': HTMLElement;

    Then to define your component's template function.

    function UpdateUser() {
      const [username, setUsername] = useState('');
      const [haircolor, setHaircolor] = useState('Black');
      const [updateUser, { data }] = useMutation(UpdateUserMutation);
      const variables = { username, haircolor };
      const nickname = data?.updateUser?.nickname ?? 'nothing';
      return (
          <label> Name
            <input type="text" oninput={e => setUsername(e.target.value)}/>
          <label> Hair Colour
            <select oninput={e => setHaircolor(e.target.value)}>
              <option>Tutti Fruiti</option>
          <button onclick={() => updateUser({ variables })}>Save</button>
          <output hidden={!data}>We'll call you {nickname}</output>
    customElements.define('update-user', c(UpdateUser));

    πŸ—ž Subscriptions

    Subscriptions let you update your front end with real-time changes to the data graph.

    subscription NewsFlash {
    import { useSubscription, c } from '@apollo-elements/atomico';
    import { NewsFlashSubscription } from './NewsFlash.subscription.graphql';
    declare global {
      interface HTMLElementTagNameMap {
        'news-flash': HTMLElement;
    function NewsFlash() {
      const { data } = useSubscription(NewsFlashSubscription);
      return (
          Latest News: {data.news}
    customElements.define('news-flash', component(NewsFlashSubscription));

    πŸ“² With Apollo Client

    If you want your atomico components to register with the closest <apollo-client> element, you have to pass a ref to the host as the hostElement option.

    import { useHost } from '@apollo-elements/atomico';
    function Connected() {
      const ref = useHost();
      const { data } = useQuery(ConnectedQuery, { hostElement: ref.current });
      return (
        <host ref={hostElement}></host>;

    That way, <apollo-client> will be able to find your element in the DOM tree and connect to the controller which powers the hook.

    πŸ‘·β€β™‚οΈ Maintainers

    apollo-elements is a community project maintained by Benny Powers.

    Contact me on Codementor


    npm i @apollo-elements/atomico

    DownloadsWeekly Downloads






    Unpacked Size

    160 kB

    Total Files


    Last publish


    • bennyp