Skip to main content

useSettings

Overview​

The useSettings() hook is a React hook that allows you to access the settings of your app. This hook enables you to modify the settings of your app and also update distinct settings to different pages within it.

Values​

The useSettings() hook provides the following variables, allowing you to customize the settings of your app.

ValueTypeDescription
settingsSettingsThe settings of your app.
isSettingsChangedbooleanIndicates whether the initial settings changed.
updateSettings(settings: Partial<Settings>, options?: UpdateSettingsOptions) => voidA function that updates the settings of your app.
resetSettings() => voidA function that reset the settings to the initial settings.
updatePageSettings(settings: Partial<Settings>) => () => voidA function that updates the settings of a specific page.
export type Settings = {
  mode?: Mode
  skin?: Skin
  semiDark?: boolean
  layout?: Layout
  navbarContentWidth?: LayoutComponentWidth
  contentWidth?: LayoutComponentWidth
  footerContentWidth?: LayoutComponentWidth
  primaryColor?: string
}
type UpdateSettingsOptions = {
  updateCookie?: boolean
}

The updateCookie prop allows you to update the settings of your app in the browser's cookies. By default, this prop is set to true.

Usage​

To utilize the useSettings() hook, please refer to the following examples:

Mode​

The mode property in the Settings type is used to define the visual mode of your application. It can be used to switch between different mode, such as a light, dark, or a system mode defined within your application.

Here's an example of how you can use the mode property:

'use client'

// Type Imports
import type { Settings } from '@core/contexts/settingsContext'

// Hook Imports
import { useSettings } from '@core/hooks/useSettings'

const SettingsMode = () => {
  // Hooks
  const { settings, updateSettings } = useSettings()

  const handleChange = (field: keyof Settings, value: Settings[keyof Settings]) => {
    updateSettings({
      [field]: value
    })
  }

  return (
    <div className='flex justify-between'>
      <form>
        <p>Mode:</p>
        <input
          type='radio'
          id='dark'
          name='mode'
          value='dark'
          checked={settings.mode === 'dark'}
          onChange={() => handleChange('mode', 'dark')}
        />
        <label htmlFor='dark'>Dark</label>
        <input
          type='radio'
          id='light'
          name='mode'
          value='light'
          checked={settings.mode === 'light'}
          onChange={() => handleChange('mode', 'light')}
        />
        <label htmlFor='light'>Light</label>
        <input
          type='radio'
          id='system'
          name='mode'
          value='system'
          checked={settings.mode === 'system'}
          onChange={() => handleChange('mode', 'system')}
        />
        <label htmlFor='system'>System</label>
      </form>
      <p>value:{settings.mode}</p>
    </div>
  )
}

export default SettingsMode

Skin​

The skin property in the Settings type is used to define the visual skin of your application. It can be used to switch between different skins, such as default and bordered.

Here's an example of how you can use the skin property:

'use client'

// Type Imports
import type { Settings } from '@core/contexts/settingsContext'

// Hook Imports
import { useSettings } from '@core/hooks/useSettings'

const SettingsSkin = () => {
  // Hooks
  const { settings, updateSettings } = useSettings()

  const handleChange = (field: keyof Settings, value: Settings[keyof Settings]) => {
    updateSettings({
      [field]: value
    })
  }

  return (
    <div className='flex justify-between'>
      <form>
        <p>Skin:</p>
        <input
          type='radio'
          id='default'
          name='skin'
          value='default'
          checked={settings.skin === 'default'}
          onChange={() => handleChange('skin', 'default')}
        />
        <label htmlFor='default'>Default</label>
        <input
          type='radio'
          id='border'
          name='skin'
          value='bordered'
          checked={settings.skin === 'bordered'}
          onChange={() => handleChange('skin', 'bordered')}
        />
        <label htmlFor='border'>Border</label>
      </form>
      <p>value:{settings.skin}</p>
    </div>
  )
}

export default SettingsSkin

SemiDark​

The semiDark property in the Settings type is used to define a semi-dark mode in your application.

Here's an example of how you can use the semiDark property:

'use client'

// Type Imports
import type { Settings } from '@core/contexts/settingsContext'

// Hook Imports
import { useSettings } from '@core/hooks/useSettings'

const SettingsSemiDark = () => {
  // Hooks
  const { settings, updateSettings } = useSettings()

  const handleChange = (field: keyof Settings, value: Settings[keyof Settings]) => {
    updateSettings({
      [field]: value
    })
  }

  return (
    <div className='flex justify-between'>
      <form>
        <input
          type='checkbox'
          id='semiDark'
          name='semiDark'
          checked={settings.semiDark}
          onChange={() => handleChange('semiDark', !settings.semiDark)}
        />
        <label id='semiDark'>Semi Dark</label>
      </form>
      <p>Value:{settings.semiDark?.toString()}</p>
    </div>
  )
}

export default SettingsSemiDark

Layout​

The layout property in the Settings type is used to define the layout structure of your application. It can be used to switch between different layout styles such as vertical, horizontal, and collapsed.

Here's an example of how you can use the layout property:

'use client'

// Type Imports
import type { Settings } from '@core/contexts/settingsContext'

// Hook Imports
import { useSettings } from '@core/hooks/useSettings'

const SettingsLayout = () => {
  // Hooks
  const { settings, updateSettings } = useSettings()

  const handleChange = (field: keyof Settings, value: Settings[keyof Settings]) => {
    updateSettings({
      [field]: value
    })
  }

  return (
    <div className='flex justify-between'>
      <form>
        <p>Layout:</p>
        <input
          type='radio'
          id='vertical'
          name='layout'
          value='vertical'
          checked={settings.layout === 'vertical'}
          onChange={() => handleChange('layout', 'vertical')}
        />
        <label htmlFor='vertical'>Vertical</label>
        <input
          type='radio'
          id='collapsed'
          name='layout'
          value='collapsed'
          checked={settings.layout === 'collapsed'}
          onChange={() => handleChange('layout', 'collapsed')}
        />
        <label htmlFor='collapsed'>Collapsed</label>
        <input
          type='radio'
          id='horizontal'
          name='layout'
          value='horizontal'
          checked={settings.layout === 'horizontal'}
          onChange={() => handleChange('layout', 'horizontal')}
        />
        <label htmlFor='horizontal'>Horizontal</label>
      </form>
      <p>Value:{settings.layout}</p>
    </div>
  )
}

export default SettingsLayout

The navbarContentWidth property in the Settings type is used to define the width of the navigation bar content in your application. It can be used to switch between different width styles such as compact and wide.

Here's an example of how you can use the navbarContentWidth property:

'use client'

// Type Imports
import type { Settings } from '@core/contexts/settingsContext'

// Hook Imports
import { useSettings } from '@core/hooks/useSettings'

const SettingsNavbarContentWidth = () => {
  // Hooks
  const { settings, updateSettings } = useSettings()

  const handleChange = (field: keyof Settings, value: Settings[keyof Settings]) => {
    updateSettings({
      [field]: value
    })
  }

  return (
    <div className='flex justify-between'>
      <form>
        <p>Navbar Content:</p>
        <input
          type='radio'
          id='compact'
          name='content'
          value='compact'
          checked={settings.navbarContentWidth === 'compact'}
          onChange={() => handleChange('navbarContentWidth', 'compact')}
        />
        <label htmlFor='compact'>Compact</label>
        <input
          type='radio'
          id='wide'
          name='content'
          value='wide'
          checked={settings.navbarContentWidth === 'wide'}
          onChange={() => handleChange('navbarContentWidth', 'wide')}
        />
        <label htmlFor='wide'>Wide</label>
      </form>
      <p>Value:{settings.navbarContentWidth}</p>
    </div>
  )
}

export default SettingsNavbarContentWidth

ContentWidth​

The contentWidth property in the Settings type is used to define the width of the main content area in your application. It can be used to switch between different width styles such as compact and wide.

Here's an example of how you can use the contentWidth property:

'use client'

// Type Imports
import type { Settings } from '@core/contexts/settingsContext'

// Hook Imports
import { useSettings } from '@core/hooks/useSettings'

const SettingsContentWidth = () => {
  // Hooks
  const { settings, updateSettings } = useSettings()

  const handleChange = (field: keyof Settings, value: Settings[keyof Settings]) => {
    updateSettings({
      [field]: value
    })
  }

  return (
    <div className='flex justify-between'>
      <form>
        <p>Content:</p>
        <input
          type='radio'
          id='compact'
          name='content'
          value='compact'
          checked={settings.contentWidth === 'compact'}
          onChange={() => handleChange('contentWidth', 'compact')}
        />
        <label htmlFor='compact'>Compact</label>
        <input
          type='radio'
          id='wide'
          name='content'
          value='wide'
          checked={settings.contentWidth === 'wide'}
          onChange={() => handleChange('contentWidth', 'wide')}
        />
        <label htmlFor='wide'>Wide</label>
      </form>
      <p>Value:{settings.contentWidth}</p>
    </div>
  )
}

export default SettingsContentWidth

footerContentWidth​

The footerContentWidth property in the Settings type is used to define the width of the footer content in your application. It can be used to switch between different width styles such as compact and wide.

Here's an example of how you can use the footerContentWidth property:

'use client'

// Type Imports
import type { Settings } from '@core/contexts/settingsContext'

// Hook Imports
import { useSettings } from '@core/hooks/useSettings'

const SettingsFooterContentWidth = () => {
  // Hooks
  const { settings, updateSettings } = useSettings()

  const handleChange = (field: keyof Settings, value: Settings[keyof Settings]) => {
    updateSettings({
      [field]: value
    })
  }

  return (
    <div className='flex justify-between'>
      <form>
        <p>Footer Content:</p>
        <input
          type='radio'
          id='compact'
          name='content'
          value='compact'
          checked={settings.footerContentWidth === 'compact'}
          onChange={() => handleChange('footerContentWidth', 'compact')}
        />
        <label htmlFor='compact'>Compact</label>
        <input
          type='radio'
          id='wide'
          name='content'
          value='wide'
          checked={settings.footerContentWidth === 'wide'}
          onChange={() => handleChange('footerContentWidth', 'wide')}
        />
        <label htmlFor='wide'>Wide</label>
      </form>
      <p>Value:{settings.footerContentWidth}</p>
    </div>
  )
}

export default SettingsFooterContentWidth

primaryColor​

The primaryColor property in the Settings type is used to define the primary color of your application. It can be used to switch between different primary colors defined within your application.

Here's an example of how you can use the primaryColor property:

'use client'

// Type Imports
import type { Settings } from '@core/contexts/settingsContext'

// Hook Imports
import { useSettings } from '@core/hooks/useSettings'

const SettingsPrimaryColor = () => {
  // Hooks
  const { settings, updateSettings } = useSettings()

  const handleChange = (field: keyof Settings, value: Settings[keyof Settings]) => {
    updateSettings({
      [field]: value
    })
  }

  return (
    <main className='p-4 flex-grow'>
      <div className='flex flex-col gap-4'>
        <p>Change the primary color from below input</p>
        <input
          type='color'
          value={settings.primaryColor}
          onChange={event => handleChange('primaryColor', event.target.value)}
        />
        <p>Primary Color: {settings.primaryColor}</p>
      </div>
    </main>
  )
}

export default SettingsPrimaryColor

Change/Reset SettingsMode​

In your application, you may need to change or reset the settings properties based on user interactions or other requirements. This can be achieved using the resetSettings function provided by the useSettings hook.

Here's an example of how you can change a setting:

'use client'

// Type Imports
import type { Settings } from '@core/contexts/settingsContext'

// Hook Imports
import { useSettings } from '@core/hooks/useSettings'

const SettingsChanged = () => {
  // Hooks
  const { settings, updateSettings, isSettingsChanged, resetSettings } = useSettings()

  const handleChange = (field: keyof Settings, value: Settings[keyof Settings]) => {
    updateSettings({
      [field]: value
    })
  }

  return (
    <main className='p-4 flex-grow'>
      <div className='flex justify-between'>
        <form>
          <p>Mode:</p>
          <input
            type='radio'
            id='dark'
            name='mode'
            value='dark'
            checked={settings.mode === 'dark'}
            onChange={() => handleChange('mode', 'dark')}
          />
          <label htmlFor='dark'>Dark</label>
          <input
            type='radio'
            id='light'
            name='mode'
            value='light'
            checked={settings.mode === 'light'}
            onChange={() => handleChange('mode', 'light')}
          />
          <label htmlFor='light'>Light</label>
          <input
            type='radio'
            id='system'
            name='mode'
            value='system'
            checked={settings.mode === 'system'}
            onChange={() => handleChange('mode', 'system')}
          />
          <label htmlFor='system'>System</label>
        </form>
        <p>{isSettingsChanged && 'value:' + settings.mode}</p>
      </div>
      {isSettingsChanged && <button onClick={resetSettings}>Reset</button>}
    </main>
  )
}

export default SettingsChanged

updatePageSettings​

In your application, you may need to update the settings of a specific page. This can be achieved using the updatePageSettings function provided by the useSettings hook. note that this settings will be applied to the specific page only and not the whole app.

When using Material-UI's theme object to apply colors in your components along with updatePageSettings for a particular page, you might encounter a class mismatch issue between the server and the client. This happens when the server-side rendered markup doesn't match the client-side rendered markup, often due to differences in the theme settings.

This issue can be particularly prevalent on pages where users have specific settings that affect the theme, as these settings might not be taken into account during server-side rendering, leading to a mismatch when the client-side rendering takes place.

To avoid this issue, it's recommended to use CSS variables for colors instead of using the theme object. For example, instead of using theme.palette.primary.main, you can use 'var(--mui-palette-primary-main)'. This way the className will be consistent between server-side and client-side rendering

Here's an example of how you can change a setting in a particular page:

'use client'

// React Imports
import { useEffect } from 'react'

// Component Imports
import { useSettings } from '@core/hooks/useSettings'

const YourComponent = () => {
  // Hooks
  const { updatePageSettings } = useSettings()

  useEffect(() => {
    return updatePageSettings({
      mode: 'dark'
    })
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [])

  return <h1>Hello World</h1>
}

export default YourComponent