Typesafe Data Attributes illustration showing code editor with type hints

Typesafe Data Attributes In Astro

Building a typesafe system with intellisense for data attributes in Astro.

Published on: Apr 14, 2025

Time to complete: 20 minutes

Why Data Attributes Matter in Modern Web Development

Data attributes let you store extra information in HTML elements. They’re perfect for passing data between HTML and JavaScript without breaking standards. In Astro, they’re very useful to pass data from props into the custom component constructor.

The standard format uses data- prefixes and kebab-case in the html element. For example, data-theme-type="dark" becomes camelCase dataset.themeType in JavaScript. Unforunately there’s no typesafety for the data attributes, until now!

Use Cases For Global Data Attributes

Global data attributes are useful when there is a script that can be used on any or most elements.

Copy To Clipboard
Animation Presets
Tooltips

Use Cases For Component-Specific Data Attributes

Component-specific data attributes are useful when there is a script that can be used on a specific component.

Passing data to a component script
State Management
Unique Animation Presets

Before getting started

Let’s define the goals for our typesafety system:

Intellicense and type validation on the html element
HTMLElement dataset Intellicense and type validation in Typescript
Intellicense for custom components with unique data attributes in the both the html definition and the component constructor script.
Easily extend the attributes for custom components and html elements.

Known Limitations

Data attribute values are always compiled to strings, so we need to parse them to the correct type when interacting with them in the script. Objects must be JSON.stringify() when setting in both the html element and TypeScript, and JSON.parse() when getting in TypeScript.

We can however set the data attribute to a number, boolean, string, or string union, and it will be compiled correctly to a string. Keep in mind when getting the data it will always be a string.

Autocomplete for global data attribute names will not appear in the html element, but it will show type validation.

There is no intellicense or type checking for custom data attributes directly in the <custom-component> html element, but there is for the global data attributes.

Benefits of Type-Safe Data Attributes

Editor autocomplete
Runtime type safety
Component-specific attributes
Improved developer experience

Creating Your First Type-Safe Attribute System

Start by creating a TypeScript declaration file src/custom-attributes.d.ts. Let’s start with the global data attributes that are accessible on all html elements. Let’s start with varying types including ones we don’t want, like an object, to test the typesafety works.

1
type GlobalDataAttributes = CustomDataset<{
2
  'data-animate-speed': number;
3
  'data-animate-direction': 'left' | 'right' | 'top' | 'bottom';
4
  'data-close-side-menu': boolean;
5
  'data-clipboard-data': string;
6
  'data-obj': {
7
    some: string;
8
    other: number;
9
  };
10
}>;

We will need two different versions of the data attributes, one for the html element in kebab-case and one for Typescript in camelCase. The type for html elements allows for string, string unions, number, and boolean. All other types are converted to a string, and when accessing the data from Typescript it will always be a string.

HTMLDataAttributes

Starting with the html element type transformers, let’s turn the camelCase to kebab-case.

1
type KebabData<T extends Record<string, unknown>> = {
2
  [K in keyof T as `data-${CamelToKebab<string & K>}`]: T[K];
3
};
4

5
type CamelToKebab<S extends string> = S extends `${infer T}-${infer U}` ? `${CamelToKebab<T>}-${Lowercase<U>}` : S extends `${infer T}${infer U}` ? (T extends Uppercase<T> ? (U extends `${Uppercase<string>}${string}` ? `${Lowercase<T>}${CamelToKebab<U>}` : `-${Lowercase<T>}${CamelToKebab<U>}`) : `${T}${CamelToKebab<U>}`) : S;

Now we can use the KebabData type to set global data attributes on html elements. But first lets make the types safer, so that only the allowed types are passed through, anything else will be a string.

1
type SimpleTypes = string | number | boolean | null | undefined;
2

3
type SafeTypes<T extends Record<string, unknown>> = {
4
  [K in keyof T]: T[K] extends SimpleTypes ? T[K] : string;
5
};

Now let’s put them together.

1
type HTMLDataAttributes<T extends Record<string, unknown>> = Partial<KebabData<SafeTypes<T>>>;

The result from this transformer is kebab-case with data- prefix and the allowed types for the html element.

To get the intellicense working we need to extend Astro’s type definition for the standardhtml elements and custom component elements.

1
declare namespace astroHTML.JSX {
2
  //Needed for all html tags
3
  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
4
  interface HTMLAttributes extends HTMLDataAttributes<GlobalDataAttributes> {}
5
  //Needed for custom components (global data attributes directly in <custom-component> tags)
6
  interface IntrinsicElements extends astroHTML.JSX.DefinedIntrinsicElements {
7
    [name: string]: {
8
      [name: string]: any;
9
    } & HTMLDataAttributes<GlobalDataAttributes>;
10
  }
11
}

Now we have intellicense for the global data attributes in the html elements, custom html elements, and the custom component props.

ComponentDataAttributes

On to the custom component data attributes. It’s just one more transformer since the global data attributes are already camelCase.

1
type ComponentDataAttributes<T extends object> = Partial<
2
  SafeTypes<
3
    {
4
      [K in keyof T]: T[K] extends string ? T[K] : string;
5
    } & {
6
      //Set value below to either:
7
      //never: strict typing on custom components.
8
      // string: loose (can set and look for any dataset that is declared)
9
      [K: string]: string;
10
    }
11
  >
12
>;

Now let extend the DOMStringMap to include the component data attributes. After this our dataset will have intellicense in TypeScript.

1
interface DOMStringMap extends ComponentDataAttributes<GlobalDataAttributes> {}

Create a new file src/types.d.ts to export the types for the custom component.

1
//Needed for custom component props to extend the global data attributes
2
export type HTMLGlobalDataAttributes = HTMLDataAttributes<GlobalDataAttributes>;
3
// Needed for custom components (global data attributes in imported <CustomComponent> tags)
4
export type HTMLAttributesWithData<T> = import('astro/types').HTMLAttributes<T> & HTMLGlobalDataAttributes;
5
//Export here to use in the components since Astro will not import `HTMLDataAttributes` from `src/custom-attributes.d.ts`
6
export type HTMLData<T> = HTMLDataAttributes<T>;

Custom Component Data Attributes

Let’s cover the custom component data attributes. For this we will create a folder for our custom component with three files:

1
src/
2
   └── components
3
      └── my-component
4
         ├── MyComponent.astro
5
         ├── index.ts
6
         └── data.ts

src/components/my-component/data.ts Define the component data attributes and an exported type for the html data attributes.

1
export type MyComponentDataAttributes = {
2
  hello?: number;
3
  world?: 'works' | 'with' | 'unions';
4
};

src/components/my-component/index.ts Define the constructor class for the custom component and import the data attributes. Declare the dataset in the class to get dataset intellicense in the class.

1
import type { MyComponentDataAttributes } from './data';
2

3
class MyComponent extends HTMLElement {
4
  declare dataset: DOMStringMap & ComponentDataAttributes<MyComponentDataAttributes>;
5
  constructor() {
6
    super();
7
    if (Number(this.dataset.hello) === 10) {
8
      console.log(this.dataset.hello);
9
    }
10
    if (this.dataset.world === 'works') {
11
      console.log(this.dataset.world);
12
    }
13
  }
14
}
15

16
customElements.define('my-component', MyComponent);

Lastly create the file src/components/my-component/MyComponent.astro and use the HTMLAttributesWithData type for the props.

1
---
2
import type { HTMLAttributesWithData, HTMLData } from '@/types';
3
import type { HTMLMyComponentDataAttributes } from './data';
4

5
export interface Props
6
  extends HTMLAttributesWithData<'div'>,
7
    HTMLData<HTMLMyComponentDataAttributes> {
8
  text: string;
9
}
10

11
const { 'data-animate-direction': animateDirection, ...rest } = Astro.props;
12

13
console.log(animateDirection);
14
---
15
<div data-animate-direction={animateDirection} data-animate-speed={100} {...rest}>
16
{text}
17
</div>

I prefer to define a prop that sets the value of the attribute. This way you can set the attribute in the html element via the prop instead of the dataset, and make it required if needed.

1
---
2
import type { HTMLAttributesWithData, HTMLData } from '@/types';
3
import type { HTMLMyComponentDataAttributes } from './data';
4

5
export interface Props extends HTMLAttributesWithData<'div'>, HTMLData<HTMLMyComponentDataAttributes> {
6
  animateDirection: HTMLMyComponentDataAttributes['animateDirection'];
7
}
8

9
const { animateDirection, ...rest } = Astro.props;
10
---
11

12
<div data-animate-direction={animateDirection} {...rest}>
13
{text}
14
</div>

Note: Because data-animate-direction is also potentialy defined in ...rest we the prop value could be overwritten. To prevent this you can destructure the prop

Common Data Attribute Challenges

Remember these important details:

Numbers and booleans convert to strings in datasets
Complex objects need JSON.stringify() this includes arrays
Date objects should be converted to ISOstring before setting in the html element
Always validate values from datasets:

1
// For booleans
2
const isTrue = element.dataset.active === 'true';
3

4
// For numbers
5
const count = Number(element.dataset.count);
6

7
// convert ISOstring to Date, can return invalid date if the string is not a valid ISOstring
8
const date = new Date(element.dataset.date);
9

10
// check if the date is valid
11
const validDate = isFinite(+date);
12

13
// For objects
14
type Data = {
15
  hello: string;
16
  world: number;
17
};
18
try {
19
  //Consider using zod to validate the data attribute
20
  const data: Data = JSON.parse(element.dataset.data || '{}') as Data | {};
21
} catch (error) {
22
  console.error('Error parsing data attribute:', error);
23
}

What’s Next?

Now that you have a typesafe system for data attributes, but there’s still one issue. When queryselecting an element, the intellicense for the data attributes will not work. There’s a solution for this, you can read about it in the next article.

Custom Component Types illustration showing code editor with type hints

Custom Component Types in Astro

Learn how to create custom component types in Astro.

Apr 14, 2025

Limited Time Launch Sale

Our AstroJS starterkit is an all-in-one solution for your Astro projects. Get your project started with a professional design system, components, and documentation.

GET 60% OFF!

TLDR Full Code

1
type GlobalDataAttributes = {
2
  //Define your custom data attributes here
3
};
4

5
type ComponentDataAttributes<T extends object> = Partial<
6
  SafeTypes<
7
    {
8
      [K in keyof T]: T[K] extends string ? T[K] : string;
9
    } & {
10
      //Set value below to either:
11
      //never: strict typing on custom components.
12
      // string: loose (can set and look for any dataset that is declared)
13
      [K: string]: string;
14
    }
15
  >
16
>;
17

18
//Needed for all html tags
19
declare namespace astroHTML.JSX {
20
  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
21
  interface HTMLAttributes extends HTMLDataAttributes<GlobalDataAttributes> {}
22
}
23

24
//Needed for custom components .astro files
25
declare module 'astro/types' {
26
  type HTMLTag = keyof astroHTML.JSX.DefinedIntrinsicElements;
27
  // Extend the HTMLAttributes type to include your custom data attributes
28
  type HTMLAttributes<Tag extends HTMLTag> = Omit<astroHTML.JSX.DefinedIntrinsicElements[Tag], keyof Omit<import('astro').AstroBuiltinAttributes, 'class:list'>> & HTMLDataAttributes<GlobalDataAttributes>;
29
}
30

31
// Needed for any for interacting with elements
32
// eslint-disable-next-line @typescript-eslint/no-empty-object-type
33
interface DOMStringMap extends ComponentDataAttributes<GlobalDataAttributes> {}
34

35
type SimpleTypes = string | number | boolean | null | undefined;
36

37
type HTMLDataAttributes<T extends Record<string, any>> = Partial<KebabData<SafeTypes<T>>>;
38

39
type KebabData<T extends Record<string, unknown>> = {
40
  [K in keyof T as `data-${CamelToKebab<string & K>}`]: T[K];
41
};
42

43
type SafeTypes<T extends Record<string, any>> = {
44
  [K in keyof T]: T[K] extends SimpleTypes ? T[K] : string;
45
};
46

47
type CamelToKebab<S extends string> = S extends `${infer T}-${infer U}` ? `${CamelToKebab<T>}-${Lowercase<U>}` : S extends `${infer T}${infer U}` ? (T extends Uppercase<T> ? (U extends `${Uppercase<string>}${string}` ? `${Lowercase<T>}${CamelToKebab<U>}` : `-${Lowercase<T>}${CamelToKebab<U>}`) : `${T}${CamelToKebab<U>}`) : S;

1
//Needed for custom component props to extend the global data attributes
2
export type HTMLGlobalDataAttributes = HTMLDataAttributes<GlobalDataAttributes>;
3
// Needed for custom components (global data attributes in imported <CustomComponent> tags)
4
export type HTMLAttributesWithData<T> = import('astro/types').HTMLAttributes<T> & HTMLGlobalDataAttributes;
5
//Export here to use in the components since Astro will not import `HTMLDataAttributes` from `src/custom-attributes.d.ts`
6
export type HTMLData<T> = HTMLDataAttributes<T>;